Initial commit: gitctl

Thin CLI plus a server helper (run as the git user) to manage repos on a
personal gitolite3 + cgit server over a command=-restricted SSH key. Includes
the client, the helper, bash completion, a Claude Code skill, and docs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

1 files changed, 68 insertions, 0 deletions

diff --git a/skills/gitctl/SKILL.md b/skills/gitctl/SKILL.md
new file mode 100644
index 0000000..b701153
--- /dev/null
+++ b/skills/gitctl/SKILL.md
@@ -0,0 +1,68 @@
+---
+name: gitctl
+description: Use when the user wants to create, list, or describe repos on a personal gitolite3 + cgit server - e.g. "make a repo on my server", "add a cgit section", "set the description for repo X", "add the server remote". gitctl is the CLI that does this; do not edit gitolite.conf or cgitrc by hand.
+---
+
+# gitctl
+
+`gitctl` is a client CLI that manages repos on a personal gitolite3 + cgit
+server through a `command=`-restricted SSH key to a server-side helper. Run
+`gitctl --help` (and `gitctl <group> --help`) for the full flag list; this skill
+is about *when* to use it and the *gotchas*, not re-listing flags.
+
+If `gitctl` is not on PATH or no `~/.config/gitctl/config.toml` exists, the tool
+is not set up on this machine - point the user at the project README ("SSH
+setup" and "Client install") rather than guessing.
+
+## When to use
+
+- User wants a NEW repo on the server -> `gitctl repo create`
+- List/add cgit sections (categories) -> `gitctl sections list|add`
+- Set a repo's cgit description -> `gitctl repo desc`
+- Add the server as a git remote in the CWD repo -> `gitctl repo add-remote`
+- Force a cgit description re-sync -> `gitctl sync`
+
+Do NOT hand-edit `gitolite.conf`, the server's `cgitrc`, or `repo.desc=`.
+gitctl owns those edits and keeps them idempotent and backed up.
+
+## Creating a repo (the two-phase flow)
+
+```
+gitctl repo create <name> --section <Section> [--desc "..."] [--owner "..."]
+```
+
+Phase 1 edits the local gitolite-admin clone, shows the diff, **asks y/N**,
+commits, pushes, then polls until gitolite builds the bare repo. Phase 2 adds
+it to cgit under the section and (if given) sets the description.
+
+Then wire up the new repo for the user:
+```
+gitctl repo add-remote <name> --remote-name origin
+git push -u origin master
+```
+
+## Gotchas
+
+- **`repo create` prompts y/N -> it needs a TTY.** Do not run it through a
+  non-interactive pipe expecting it to just work; let the user confirm, or have
+  them run it. The phase-1 push may also require a hardware-key touch/PIN, which
+  only works interactively.
+- **If the push fails after the local commit** (key refused, auth failure): the
+  gitolite-admin commit is made but unpushed. The user pushes manually
+  (`git -C <admin-clone> push origin <branch>`), then you RE-RUN the same
+  `gitctl repo create` command. It is idempotent: it detects the existing
+  stanza, skips phase 1, and finishes phase 2. Do not start over.
+- **Section names with spaces must be quoted**: `--section "My Sites"`.
+- **No delete verb.** Removing a repo/section is deliberately manual (server
+  side). Do not script deletion through gitctl.
+- **`--desc` is the only way to set a cgit description.** It writes the bare
+  repo's `description` file and runs the sync script (the single writer of
+  `repo.desc=`). Never write `repo.desc=` directly.
+
+## Discovering current state
+
+```
+gitctl sections list          # existing cgit sections (categories)
+```
+There is no repo-list verb on the client; a section is required for create, so
+list sections first if unsure which category to use.