# 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`](../../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

- [Docs index](docs/README.md)
