Command reference¶
Every command takes --md for Markdown output meant for agents, and -h for its flags.
usage: gion <command> [args]
commands:
ls-refs <remote> [--prefix p]... list remote refs (protocol v2)
cat <remote> <rev>:<path> print a file's raw bytes
ls <remote> [<rev>[:<dir>]] list a directory (default HEAD:)
find <remote> [<rev>] <pattern> search file paths across the whole repo
(substring, or glob with * ? ** [])
grep <remote> [<rev>] <regex> [--path p]... [-i] [-l] [--local|--forge]
search file contents: scans locally when the candidate files are
few (--max-files, default 5000), else asks GitHub code search for
candidates and verifies them locally
clone <remote> <dir> [--ref r] [--path p]... [--no-git] [--no-deps]
light workspace: only the chosen paths (default all) at one
commit, no history. it has a local .git that gion keeps in step,
so pre-commit, git diff and git status work (--no-git: none).
paths their manifests depend on locally (file: packages, path
crates, go.work, ...) are added too, or listed if over 5 GB
(--no-deps: neither). Then, inside it:
status changed files vs. the clone
(honors .gitignore)
diff [<path>...] [--stat|--name-only|--name-status]
your edits as a unified diff
log [<path>] / blame <path> history of the workspace's commit
rebase [<onto>] replay your branch onto <onto> (default:
the default branch) and push it. on a
conflict, fix the marked files, then
rebase --continue | --skip | --abort
add <path>... [--no-deps] widen the workspace with more paths and
their local dependencies (a new path
just joins the scope)
sync pull upstream changes into files you
haven't edited; stops on conflicts
switch <branch> move the workspace to an existing branch;
keeps your edits, commits go there
commit -m <msg> [--branch b | --to b] [--no-verify]
push workspace changes. default: first
commit creates a branch, later ones
update it. --to b pushes onto existing b.
runs pre-commit and commit-msg
hooks first
commit <remote> -m <msg> <path>=<local>... [--rm <path>]...
[--branch <name> [--onto <rev> | --orphan] | --to <branch>]
build a commit from the changes and push it; no checkout needed.
each file's executable bit comes from the local file.
default: new branch gion/<timestamp> from HEAD.
--to: update an existing branch (compare-and-swap, retries on
upstream moves that don't touch your paths).
diff <remote> [<rev>] [<rev>] [--path p]... [--stat|--name-only|--name-status] [-U n]
what changed between two commits (a b or a..b), or what one commit
changed (default HEAD). only the trees and files that differ are fetched
log <remote> [<rev>] [-n N] [--path p] [--oneline]
commits newest first; --path: only those that changed it (GitHub
answers that fast; elsewhere history is walked locally)
blame <remote> <rev>:<path> [-L a,b]
which commit last changed each line (GitHub GraphQL, or locally)
rebase <remote> <branch> [--onto <rev>]
the same without a workspace; stops (pushing nothing) on conflicts
branch rename <remote> <old> <new>
rename a branch (GitHub keeps its open PRs). in a workspace:
branch rename [<old>] <new>, <old> defaulting to the workspace's
branch, which then follows the new name
tag <remote> <name> [<rev>] [-m <msg>]
create a tag on the remote (annotated with -m); never moves one
gc [--max SIZE] trim the cache (~/.gion) now and show its
size; it's also trimmed automatically
skill install [--project] install the agent skill for Claude Code and
agents reading .agents/skills (home dir,
or the current project with --project)
version print the gion version
<remote> is a URL or GitHub "owner/repo".
<rev> is a branch, tag, HEAD or commit id, with optional ~N / ^N steps
(main~2). Short commit ids work on GitHub.
flags: --md markdown output for agents
`gion help --md` prints a usage guide for agents.
gion add¶
--md markdown output
--no-deps don't add the paths that manifests under the new paths depend on
gion blame¶
-L string only lines a,b (1-based, inclusive)
--local compute locally even when the forge could answer
--md markdown output
gion branch¶
--md markdown output
gion cat¶
--md accepted for uniformity; output is always the raw bytes
gion clone¶
--md markdown output
--no-deps don't add the paths that manifests under --path depend on
--no-git write no .git (by default gion keeps one in step for pre-commit, git diff and other git-based tools)
--path value path to include (repeatable; default whole repo)
--ref string rev to clone (default HEAD)
gion commit¶
--branch string new branch to create (default gion/<timestamp>)
-m string commit message (required)
--md markdown output
--no-verify skip the pre-commit and commit-msg hooks
--onto string base rev for a new branch (default HEAD)
--orphan make a root commit with no parent (e.g. in an empty repo)
--rm value path to delete (repeatable)
--to string existing branch to update with compare-and-swap
gion diff¶
-U int lines of context (default 3)
--md markdown output
--name-only print only changed paths
--name-status print changed paths with A/M/D
--path value limit to this path (repeatable)
--stat print lines added and removed per file
gion find¶
--limit int stop after this many results (0 = all)
--md markdown output
gion gc¶
--max string size cap for this run (default $GION_CACHE_MAX or 1GB)
--md markdown output
gion grep¶
--forge use the forge's code search to pick files
-i case-insensitive
-l print only names of files with matches
--local scan every candidate file, however many
--max-files int above this many candidates, use code search (default 5000)
--md markdown output
--path value only files under this path or matching this glob (repeatable)
gion log¶
--local walk history locally even when the forge could answer
--md markdown output
-n int number of commits (default 20)
--oneline one line per commit
--path string only commits that changed this path
gion ls¶
--md markdown output
gion ls-refs¶
--md accepted for uniformity; output is always git ls-remote's format
--prefix value ref prefix to list (repeatable; default HEAD, refs/heads/)
--time print elapsed time to stderr
gion rebase¶
--abort put everything back as before the rebase
--continue finish the stopped commit with your resolved files
--md markdown output
--onto string remote mode: rev to rebase onto (default: the default branch)
--skip drop the stopped commit
gion skill¶
--md markdown output
--project install into the current directory instead of your home
gion status¶
--md markdown output
gion switch¶
--md markdown output
gion sync¶
--md markdown output
gion tag¶
-m string message; makes an annotated tag (recommended for releases)
--md markdown output
gion version¶
--md accepted for uniformity; output is one plain line