update readme

README.md

@@ -17,6 +17,64 @@ A GitHub Desktop-style git client that runs in your terminal. Use the mouse or t
 4. **Your name and email:** the first time you commit or create a repository, gitdesk asks
    for them if git doesn't know them yet. They're saved for all your repositories.
 
+## Set up SSH for git (Windows, optional)
+
+`git-ssh-setup.ps1` sets up SSH, so pushes and Git LFS don't ask for your passphrase
+every time. It's handy when HTTPS pushes are refused as too big (see **Push over SSH** below).
+
+**Run it:** double-click `git-ssh-setup.cmd`. Run it as your normal user, not
+"Run as administrator". From PowerShell, use:
+
+```
+powershell -NoProfile -ExecutionPolicy Bypass -File .\git-ssh-setup.ps1
+```
+
+The bypass applies to that one run only. Your system's execution policy isn't changed.
+
+It asks for the SSH host. You can type `git.example.com`, `git.example.com:2222`, or paste an
+SSH clone URL. Next time it offers the host you used last: press Enter to keep it, or type
+another one to set up a second server. Then it:
+
+1. turns on Windows' `ssh-agent` service. This step shows a UAC prompt, and only when the
+   service needs turning on. If the OpenSSH client is missing, it installs that too.
+2. creates an ed25519 key `~/.ssh/id_ed25519_gitea` (it asks for a passphrase), or reuses the
+   one that's already there.
+3. loads the key into ssh-agent. Windows keeps it loaded across reboots.
+4. adds a `Host` entry for the server to `~/.ssh/config`. If one already exists, it leaves it
+   alone and shows what it would have written.
+5. points git at Windows' OpenSSH (`core.sshCommand`), so git uses the agent. It also sets
+   `lfs.ssh.automultiplex false`, which stops Git LFS transfers over SSH from hanging.
+6. shows your public key and copies it to the clipboard. Add it in Gitea: your avatar >
+   Settings > SSH / GPG Keys > Add Key.
+7. verifies the key in Gitea (optional). Click **Verify** next to the key, paste the token
+   into the script, then paste the signature it copies back into Gitea.
+8. tests the connection with `ssh -T`.
+
+You can run it again safely. It reuses the key, doesn't add it to the agent twice, and never
+changes an existing `~/.ssh/config` entry.
+
+| Option | What it does |
+|---|---|
+| `-HostName git.example.com` | Skips the host prompt. `-HostName ""` skips the config entry and the test. |
+| `-Port 2222` | SSH port (default 22). |
+| `-User git` | SSH user (default `git`, which is right for Gitea, GitHub and GitLab). |
+| `-KeyName id_ed25519_github` | Key file name in `~/.ssh` (default `id_ed25519_gitea`). |
+| `-Comment "label"` | Label shown in Gitea's key list (default `user@computer`). |
+| `-Force` | Replaces the existing key instead of reusing it. |
+| `-NoVerify` | Skips the Gitea verify step (e.g. for GitHub). |
+| `-Token <hex>` | Signs this Gitea verify token without asking for it. |
+| `-NoTest` | Skips the connection test. |
+
+Gitea's verify token expires quickly. If Gitea rejects the signature, click **Verify** again
+and run it again with only the new token:
+
+```
+powershell -NoProfile -ExecutionPolicy Bypass -File .\git-ssh-setup.ps1 -NoTest -Token <new token>
+```
+
+If the site is behind Cloudflare's proxy, use a hostname or IP that reaches the server
+directly. SSH doesn't go through the proxy.
+
 ## Build a standalone executable (optional)
 
 This makes a single file that runs without Python or Textual installed.