91 lines
5.4 KiB
Markdown
91 lines
5.4 KiB
Markdown
# 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
|