upload commit

README.md

@@ -0,0 +1,90 @@
+# gitdesk
+
+A GitHub Desktop-style git client that runs in your terminal. Use the mouse or the keyboard.
+
+## Setup
+
+1. Install Python 3.9+ and git (2.25 or newer).
+2. Install the one dependency: `python -m pip install -r requirements.txt`
+   (or just run gitdesk once and say yes when it offers to install it).
+
+## Build a standalone executable (optional)
+
+This makes a single file that runs without Python or Textual installed.
+
+- **Windows:** double-click `build.bat`. You get `dist\gitdesk.exe`.
+- **Linux / macOS:** run `./build.sh`. You get `dist/gitdesk`.
+
+Build on the system you want to run it on: a Windows exe has to be built on Windows.
+The scripts use their own `.build-venv` folder and don't touch your Python install.
+The exe takes a second or two to start because it unpacks itself first.
+
+## Run
+
+| | |
+|---|---|
+| **Windows** | `gitdesk.bat` inside a repo folder, or `gitdesk.bat C:\path\to\repo`. Windows Terminal gives the best mouse support and symbols. |
+| **Linux / macOS** | `python3 gitdesk.py` inside a repo, or `python3 gitdesk.py ~/path/to/repo` |
+
+Tip: put this folder on your PATH (Windows), or symlink it on Linux/macOS
+(`ln -s "$PWD/gitdesk.py" ~/.local/bin/gitdesk`). Then you can type `gitdesk` in any repo.
+
+## What's on screen
+
+- **Top bar:**
+  - **Current repository:** click it to open the picker. It lists your recent repos
+    and has **Add local repository…**, **New repository…** and **Clone repository…**.
+  - **Current branch:** click to switch branches or create one.
+  - **Fetch / Pull / Push / Publish:** one button that changes with the state of your
+    branch, like GitHub Desktop's. If the repo has no remote yet, it shows **No remote**:
+    click it to add the URL of an empty repo you created on GitHub or Gitea, then publish.
+  - **More:** lists every action.
+- **Startup:** gitdesk reopens the repository you had open last. If you start it inside
+  a repo folder, or pass a path (`gitdesk C:\path\to\repo`), it opens that one instead.
+- **Add local repository** (`o`): type a path, or click **Choose…** to pick the folder.
+  If the folder isn't a git repository yet, it offers **Create a repository here**:
+  the files already in it go into the first commit (pick the Unity .gitignore for a Unity
+  project so Library/ and Temp/ stay out).
+- **Choose… buttons** (Add local, New repository, Clone) open the normal folder picker:
+  the Explorer "Select Folder" window on Windows, Finder on macOS, and zenity/kdialog on
+  Linux desktops. With no desktop (e.g. over SSH) you get a folder browser inside the terminal.
+  On Windows the Explorer picker needs Python's tkinter, which the python.org installer
+  includes by default. Without it you get the older Windows folder dialog instead.
+  The same goes for the exe: build it with a Python that has tkinter.
+- **New repository:** choose a name, description and folder, a README, a .gitignore
+  template (Unity, Python, Node, Visual Studio), an MIT license, and an optional remote URL.
+  It makes the first commit for you.
+- **Clone repository:** paste an HTTPS or SSH URL. The folder name fills in automatically
+  and progress shows in the top bar. If the server needs a password, use **Retry in terminal**.
+- **Changes tab:** changed files with checkboxes. Ticked files go into the commit.
+  Click a file to see its diff, then **Discard** it if you don't want those changes.
+  Discard keeps a backup in Stashed changes, so it can be undone. More → Discard
+  ticked changes does several files at once. Below the list are Stash all / Stashed, and
+  the commit summary + description.
+- **History tab:** recent commits (↑ = not pushed yet). Click one to see what changed,
+  or **View on GitHub** to open that commit's page.
+- **View on GitHub** (`g`, More menu, or the card on the "No local changes" screen) opens
+  the repo's web page, worked out from the remote URL. It works for GitHub, Gitea,
+  GitLab and Bitbucket, over SSH or HTTPS, and any token in the URL is left out.
+  If the address can't be worked out (e.g. SSH goes through a separate hostname), set it once:
+  `git config gitdesk.webUrl https://git.example.com/owner/repo`
+- **Log** (`l`): shows every git command gitdesk ran and what git printed.
+
+## Behaviour
+
+- It refreshes every 3 seconds and fetches in the background every 5 minutes.
+- **Pull blocked by your local changes:** it offers *Stash, pull & re-apply*.
+  - If re-applying clashes, the file shows the `<<<<<<< ======= >>>>>>>` markers.
+  - Fix the file, then click **Mark as resolved**. The stash is kept until you drop it.
+- **Pull hits a merge conflict:** choose *Resolve conflicts* (fix files, Mark as resolved,
+  Commit merge) or *Abort merge*.
+- **Push when the remote has newer commits:** it offers *Pull, then push*.
+- **Switching branch blocked by your changes:** it offers *Stash & switch*.
+- **A network command needs a password, token, SSH passphrase or host-key confirmation:**
+  click **Retry in terminal**. gitdesk steps aside so git can ask you, then comes back.
+- **Another program has the repository busy** (GitHub Desktop, VS Code, Unity, OneDrive,
+  antivirus): gitdesk waits and retries for a few seconds. If a `.git/index.lock` is left
+  behind by a crashed git, it offers **Remove lock file & retry**.
+
+Keys: `f` fetch · `p` pull · `u` push · `b` branch · `s` stash · `t` stashes · `d` discard ·
+`o` add local repo · `n` new repo · `c` clone · `g` view on web · `l` log · `r` refresh · `space` tick/untick file · `q` quit

build.bat

@@ -0,0 +1,48 @@
+@echo off
+rem ==========================================================================
+rem  build.bat - builds gitdesk into a single Windows executable: dist\gitdesk.exe
+rem
+rem  Needs Python 3.9+ installed. Double-click it or run it from this folder.
+rem  It makes its own throwaway environment in .build-venv, so it doesn't touch
+rem  your normal Python packages.
+rem ==========================================================================
+setlocal
+cd /d "%~dp0"
+
+set "PY="
+where py >nul 2>&1 && set "PY=py -3"
+if not defined PY where python >nul 2>&1 && set "PY=python"
+if not defined PY (
+    echo Python 3 was not found. Install it from https://www.python.org/downloads/
+    goto :fail
+)
+
+echo [1/3] Creating the build environment - .build-venv ...
+if not exist ".build-venv\Scripts\python.exe" %PY% -m venv .build-venv
+if not exist ".build-venv\Scripts\python.exe" goto :fail
+set "VPY=.build-venv\Scripts\python.exe"
+
+echo [2/3] Installing PyInstaller and Textual...
+"%VPY%" -m pip install --quiet --upgrade pip
+"%VPY%" -m pip install --quiet pyinstaller -r requirements.txt
+if errorlevel 1 goto :fail
+
+echo [3/3] Building gitdesk.exe...
+rem Textual and Rich load some of their modules on demand, so bundle all of them.
+"%VPY%" -m PyInstaller --noconfirm --clean --onefile --name gitdesk ^
+    --collect-submodules textual --collect-data textual --collect-submodules rich ^
+    --specpath build --workpath build --distpath dist ^
+    gitdesk.py
+if errorlevel 1 goto :fail
+
+echo.
+echo Done: %CD%\dist\gitdesk.exe
+echo Copy it anywhere - a folder on your PATH is handy - and run "gitdesk" inside a repo.
+pause
+exit /b 0
+
+:fail
+echo.
+echo Build failed - see the messages above.
+pause
+exit /b 1

build.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+#
+# build.sh - builds gitdesk into a single executable: dist/gitdesk
+#
+# Run it on the system you want the executable for (Linux builds a Linux
+# binary, macOS builds a macOS one). For Windows use build.bat on Windows.
+# It makes its own throwaway environment in .build-venv, so it doesn't touch
+# your system Python packages.
+set -euo pipefail
+cd "$(dirname "$0")"
+
+PY=$(command -v python3 || command -v python || true)
+[[ -n $PY ]] || { echo "Python 3 wasn't found. Install it first."; exit 1; }
+
+echo "[1/3] Creating the build environment (.build-venv)..."
+if [[ ! -x .build-venv/bin/python ]]; then
+  "$PY" -m venv .build-venv || {
+    echo "Couldn't create a virtualenv. On Debian/Ubuntu: sudo apt install python3-venv"; exit 1; }
+fi
+VPY=.build-venv/bin/python
+
+echo "[2/3] Installing PyInstaller and Textual..."
+"$VPY" -m pip install --quiet --upgrade pip
+"$VPY" -m pip install --quiet pyinstaller -r requirements.txt
+
+echo "[3/3] Building..."
+# Textual and Rich load some of their modules on demand, so tell PyInstaller to
+# bundle all of them.
+"$VPY" -m PyInstaller --noconfirm --clean --onefile --name gitdesk \
+  --collect-submodules textual --collect-data textual --collect-submodules rich \
+  --specpath build --workpath build --distpath dist \
+  gitdesk.py
+
+echo
+echo "Done: $PWD/dist/gitdesk"
+echo "Copy it somewhere on your PATH (e.g. ~/.local/bin) and run 'gitdesk' inside a repo."

gitdesk.bat

@@ -0,0 +1,15 @@
+@echo off
+rem gitdesk launcher for Windows.
+rem Run it from inside a repo folder (or pass a path):  gitdesk  /  gitdesk C:\path\to\repo
+rem Needs Python 3.9+ and git. On first run it offers to install the "textual" package.
+setlocal
+set "PY="
+where py >nul 2>&1 && set "PY=py -3"
+if not defined PY where python >nul 2>&1 && set "PY=python"
+if not defined PY (
+    echo Python 3 was not found. Install it from https://www.python.org/downloads/
+    pause
+    exit /b 1
+)
+%PY% "%~dp0gitdesk.py" %*
+if errorlevel 1 pause

requirements.txt

@@ -0,0 +1 @@
+textual>=8.2