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