diff options
Diffstat (limited to 'skills')
| -rw-r--r-- | skills/gitctl/SKILL.md | 68 |
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. |