GitDesk/README.md

# 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