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. In PowerShell type .\build.bat; PowerShell won't run it without the .\. You get dist\gitdesk.exe.
• Linux / macOS: run ./build.sh. You get dist/gitdesk.

build.py does the work, and the .bat/.sh just start it. It:

• sets up its own environment in .build;
• installs PyInstaller and Textual;
• builds the exe;
• test-starts the new exe to make sure it works;
• logs everything to build.log.

If something goes wrong it says why in plain English (old exe still open, antivirus, OneDrive, no internet...). Send build.log over if the reason isn't clear.

Build on the system you want to run it on: a Windows exe has to be built on Windows. 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.

• Right-click a changed file (or press m / Shift+F10) for the same menu as GitHub Desktop:

  • Discard changes…
  • Ignore file, Ignore folder ▸ (pick which parent folder), or Ignore all .ext files. Each one adds a line to the repo's .gitignore.
  • Copy file path / relative path
  • Show in Explorer, Open in VS Code, Open with default program

  Ignoring a file git already tracks doesn't hide its changes, so if the new rule covers tracked files, gitdesk offers Stop tracking. The files stay on your disk and leave the repository in your next commit.

• 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.
• Push refused as too big over HTTPS (HTTP 413), e.g. by Cloudflare's 100 MB upload limit: gitdesk offers Push over SSH with the SSH address filled in. You can change the address, and it's remembered per repo.
  • Tick Always push this repository over SSH to set git's push URL, so pushes go over SSH while fetches stay on HTTPS.
  • If the site is behind Cloudflare, SSH needs an address that reaches the server directly: a DNS-only hostname or the server's IP.
• 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 · m file menu · q quit