nils-git-cli 0.7.3

CLI crate for nils-git-cli in the nils-cli workspace.
Documentation

git-cli

Overview

git-cli is a Rust CLI that groups Git workflow helpers behind a dispatcher. It exposes seven command groups (utils, reset, commit, branch, ci, open, completion) with consistent help / version handling: git-cli help (or -h/--help) prints top-level usage, git-cli <group> help prints group usage, and git-cli -V/--version prints the binary version.

Usage

Invoke as git-cli <group> <command> [args]. The dispatcher recognizes these groups and subcommands (matching the binary's --help output):

  • utils: zip, copy-staged (alias copy), root, commit-hash (alias hash).
  • reset: soft, mixed, hard, undo, back-head, back-checkout, remote.
  • commit: context, context-json (aliases context_json, contextjson, json), to-stash (alias stash).
  • branch: cleanup (alias delete-merged).
  • ci: pick.
  • open: repo, branch, default-branch (alias default), commit, compare, pr (aliases pull-request, mr, merge-request), pulls (aliases prs, merge-requests, mrs), issues (alias issue), actions (alias action), releases (alias release), tags (alias tag), commits (alias history), file (alias blob), blame.
  • completion: bash, zsh (writes a clap-generated completion script to stdout).

Commands

utils

  • zip: Create backup-<short-sha>.zip from HEAD using git archive.
  • copy-staged (copy): Copy staged diff to the clipboard. Use --stdout (-p/--print) to print, --both to print and copy.
  • root: Print the repository root. Use --shell to output cd -- <path> for eval.
  • commit-hash (hash): Resolve a ref to a commit SHA.

reset

  • soft|mixed|hard [N]: Rewind HEAD by N commits (default: 1) with confirmations and summaries.
  • undo: Move HEAD back to the previous reflog entry with safety checks.
  • back-head: Checkout HEAD@{1} (previous position).
  • back-checkout: Checkout the previously checked-out branch (requires non-detached HEAD).
  • remote: Reset the current branch to a remote-tracking ref. Options: --ref <remote/branch>, --remote <name>, --branch <name>, --no-fetch, --prune, --set-upstream, --clean, -y/--yes.

commit

  • context: Build a Markdown commit context from staged changes. Options: --stdout (-p/--print), --both, --no-color (or NO_COLOR), --include <path/glob> (repeatable).
  • context-json (aliases context_json, contextjson, json): Write commit-context.json and staged.patch (default: <git-dir>/commit-context). Options: --stdout, --both, --pretty, --bundle, --out-dir <path>.
  • to-stash (stash): Create a stash from a commit and optionally rewrite history via prompts.

branch

  • cleanup (delete-merged): Delete merged local branches. Options: -b/--base <ref>, -s/--squash, -w/--remove-worktrees.

ci

  • pick: Create and push a ci/<target>/<name> branch with cherry-picked commits. Options: -r/--remote <name>, --no-fetch, -f/--force, --stay.

open

  • repo [remote]: Open repository homepage.
  • branch [ref]: Open tree page for a ref (default: upstream branch).
  • default-branch [remote] (default): Open default branch tree page.
  • commit [ref]: Open commit page (default: HEAD).
  • compare [base] [head]: Open compare page.
  • pr [number] (pull-request, mr, merge-request): Open PR/MR page or create/view current-branch PR. On GitHub remotes, prefers gh pr view --web when available.
  • pulls [number] (prs, merge-requests, mrs): Open PR/MR list or specific PR/MR.
  • issues [number] (issue): Open issue list or specific issue.
  • actions [workflow] (action): Open GitHub Actions page (GitHub only). Workflow may be a file name (ci.yml/ci.yaml) for the workflow page, or any other token for an actions search.
  • releases [tag] (release): Open releases list or specific release tag.
  • tags [tag] (tag): Open tags list or specific release tag.
  • commits [ref] (history): Open commits history page.
  • file <path> [ref] (blob): Open file blob page.
  • blame <path> [ref]: Open blame page.
  • GIT_OPEN_COLLAB_REMOTE can override the remote used for collaboration pages (pr/pulls/issues/actions/releases/tags).

completion

  • bash / zsh: Print a clap-generated shell completion script to stdout (suitable for source <(git-cli completion zsh)). Any extra arguments are rejected.

Shell aliases (optional)

  • Zsh aliases live in completions/zsh/aliases.zsh.
  • Bash aliases live in completions/bash/aliases.bash.
  • gxur should be implemented via: eval "$(git-cli utils root --shell)".

Exit codes

  • 0: Success and help output.
  • 1: Operational errors or aborted confirmations.
  • 2: Usage/parse errors.

Dependencies

  • git is required for all commands.
  • git-scope is required for commit context.
  • Clipboard integration via nils-common::clipboard probes pbcopy, wl-copy, xclip, then xsel (in that order) for commit context, utils copy-staged, and any other clipboard consumer. Missing or failing clipboard tools emit a warning and the command continues. See the workspace BINARY_DEPENDENCIES.md for install hints.
  • gh is preferred for GitHub PR pages (open pr); without it the CLI falls back to the GitHub compare URL.
  • file is optionally used for MIME-based binary detection in commit context.

Docs