Refresh README and user guide for 1.2.0.

Document Homebrew upgrade and PATH shadowing, --show-path, directory
include/exclude, and related cookbook/quickstart examples.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: chtnnh

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- README and user guide refreshed for 1.2.0 (Homebrew upgrade / PATH shadowing, `--show-path`, directory `--in`/`--exclude`)
+
 ### Planned
 - `gg doctor --config` — warn on stale binary vs latest, empty `auto_enroll`, missing group members, duplicate basenames
 - `--cwd` / default `--root .` when no config root for “just this folder” workflows

CONTRIBUTING.md

@@ -31,8 +31,9 @@ Line coverage must stay **≥ 95%** (enforced in CI via `./scripts/ci.sh` / `./s
 - Prefer small, focused PRs aligned with the version roadmap in the README / docs.
 - Passthrough must shell out to `git` on `PATH` — do not reimplement porcelain.
 - Add/extend tests under `tests/` for CLI behavior.
-- Update `CHANGELOG.md` for user-visible changes.
+- Update `CHANGELOG.md` **and** user-facing docs (`README.md`, `docs/src/…`) for user-visible changes.
 - Keep reserved builtin names documented when adding commands.
+- Preview the book with `mdbook serve docs --open` when editing guide pages.
 
 ## Commit style
 

README.md

@@ -2,7 +2,7 @@
 
 **Run git across all child repositories — fast.**
 
-Docs: **https://gg.chtnnhfoundation.org/**
+Current release: **1.2.0** · Docs: **https://gg.chtnnhfoundation.org/**
 
 `gg` discovers git repos under a directory and runs git commands (or built-in insights) in parallel. One CLI for multi-checkout workspaces, client folders, and polyrepos.
 
@@ -19,46 +19,57 @@ gg --only-dirty pull
 # target an alias or group
 gg -g work fetch --all
 
+# show paths next to repo names (also: show_path = true in config)
+gg --show-path ov
+
 # top commits across selection
 gg commits -n 10
 ```
 
 ## Install
 
-### From source
+### Homebrew (tap)
 
 ```bash
-cargo install --path . --locked
-# binary: gg
+brew tap chtnnh/tap          # first time; may need: brew trust chtnnh/tap
+brew install git-gist
+# or: brew install chtnnh/tap/git-gist
+
+brew update && brew upgrade git-gist   # later releases
 ```
 
-### Homebrew (tap)
+If `gg version` still looks old after upgrading, Homebrew’s `gg` may be shadowed by `~/.cargo/bin/gg`. Check with `which -a gg`, or use `/opt/homebrew/opt/git-gist/bin/gg` (Apple Silicon) / `/usr/local/opt/git-gist/bin/gg` (Intel).
+
+### cargo-dist shell / PowerShell installer
 
 ```bash
-brew install chtnnh/tap/git-gist
+curl --proto '=https' --tlsv1.2 -LsSf https://github.com/chtnnh/git-gist/releases/latest/download/git-gist-installer.sh | sh
 ```
 
-### Debian / RPM
+Windows (PowerShell):
 
-Download `.deb` / `.rpm` from [GitHub Releases](https://github.com/chtnnh/git-gist/releases), or build with `cargo deb` / `cargo generate-rpm` (see [packaging/README.md](packaging/README.md)).
+```powershell
+irm https://github.com/chtnnh/git-gist/releases/latest/download/git-gist-installer.ps1 | iex
+```
 
-### Nix
+### From crates.io / source
 
 ```bash
-nix run github:chtnnh/git-gist -- version
-nix profile install github:chtnnh/git-gist
+cargo install git-gist --locked
+# or from this repo:
+cargo install --path . --locked
+# binary: gg
 ```
 
-### cargo-dist shell / PowerShell installer
+### Debian / RPM
 
-```bash
-curl --proto '=https' --tlsv1.2 -LsSf https://github.com/chtnnh/git-gist/releases/latest/download/git-gist-installer.sh | sh
-```
+Download `.deb` / `.rpm` from [GitHub Releases](https://github.com/chtnnh/git-gist/releases), or build with `cargo deb` / `cargo generate-rpm` (see [packaging/README.md](packaging/README.md)).
 
-Windows (PowerShell):
+### Nix
 
-```powershell
-irm https://github.com/chtnnh/git-gist/releases/latest/download/git-gist-installer.ps1 | iex
+```bash
+nix run github:chtnnh/git-gist -- version
+nix profile install github:chtnnh/git-gist
 ```
 
 Operator guide for brew/deb/rpm/nix: [packaging/README.md](packaging/README.md).
@@ -108,14 +119,16 @@ Anything else is passed through to `git` in each selected repo. Escape hatch: `g
 
 ## Configuration
 
-- Global: `~/.config/git-gist/config.toml`
+- Global: `~/.config/git-gist/config.toml` (macOS: `~/Library/Application Support/git-gist/config.toml`)
 - Local: `.gg.toml` or `.git-gist.toml` (walks up from cwd)
 - Ignore globs: config `ignore` + `.ggignore`
 
 ```toml
 schema_version = 1
 depth = 6
 jobs = 8
+theme = "vivid"
+show_path = false   # or true / use --show-path
 ignore = ["**/node_modules/**", "**/target/**"]
 
 [aliases]
@@ -144,13 +157,24 @@ tags = ["learning"]
 - `--root`, `--in` / `-i`, `--exclude` / `-x`, `-g <group>`, `--tag`, `--depth`
 - `-j` jobs, `--fail-fast`, `--dry-run`, `--timing`, `-q` / `--quiet`
 - `--only-dirty`, `--only-clean`, `--only-ahead`, `--only-behind`, …
-- `--format human|json|ndjson`, `--color auto|always|never`, `--theme`
+- `--format human|json|ndjson`, `--color auto|always|never`, `--theme`, `--show-path`
+
+Selection notes:
+
+- `--root` does not pull in aliases **outside** that tree (use `-i`).
+- `--depth` also applies to under-root aliases.
+- An existing **directory** for `-i` / `-x` includes or excludes all selected repos under that prefix.
+- Selection flags apply to reporting and multi-repo commands (`ov`, `list`, `sync`, `each`, passthrough, …). Catalog/config commands (`alias`, `group`, `config`, `hooks list`, …) ignore them.
+- Put global flags **before** external git verbs (`gg --dry-run status`). Misplaced globals after the verb error with a hint.
+
+## What’s new in 1.2.0
+
+- Faster status probes and `--only-*` filters (fewer git process spawns)
+- `show_path` / `--show-path` for human tables
+- Directory prefix `--in` / `--exclude`, depth-aware under-root aliases
+- Clearer errors when globals land after a passthrough verb
 
-Selection flags (`--root`, `--in`, `--only-*`, …) apply to reporting and multi-repo
-commands (`ov`, `list`, `sync`, `each`, passthrough, …). Catalog/config commands
-(`alias`, `group`, `config`, `hooks list`, …) ignore them. Put global flags
-**before** external git verbs (`gg --dry-run status`), since trailing flags after
-passthrough go to git.
+Full notes: [CHANGELOG.md](CHANGELOG.md).
 
 ## Documentation
 

docs/src/commands.md

@@ -6,8 +6,8 @@ See `gg --help` and per-command `--help` for the full flag list.
 
 | Command | Alias | Purpose |
 |---------|-------|---------|
-| `overview` | `ov` | Dashboard: branch, dirty/clean, ahead/behind, age, in-progress (semantic colors) |
-| `list` | `ls` | Discovered / selected repos (`--refresh` bypasses cache) |
+| `overview` | `ov` | Dashboard: branch, dirty/clean, ahead/behind, age, in-progress (semantic colors; `--show-path` adds path to the repo column) |
+| `list` | `ls` | Discovered / selected repos (`--refresh` bypasses cache; always prints name + path) |
 | `info [PATH]` | | Detailed status; optional path still respects `--only-*` / `--in` when those are set |
 | `commits -n N` | | Top-N commits across selection |
 | `worktrees` | | Worktree listing |
@@ -55,6 +55,6 @@ gg pull --rebase
 gg git -- status   # escape hatch when a name collides with a builtin
 ```
 
-Put global flags **before** the git verb: `gg --dry-run status` (not `gg status --dry-run`).
+Put global flags **before** the git verb: `gg --dry-run status` (not `gg status --dry-run`). If a common global flag appears after the verb, `gg` errors with a hint instead of forwarding it to git.
 
 Exit code is non-zero if any selected repo fails (unless the selection is empty).

docs/src/cookbook.md

@@ -6,12 +6,32 @@
 gg ov --root .
 ```
 
+## Show paths in human tables
+
+```bash
+gg --show-path ov
+gg --show-path -g work stale --days 90
+
+# persist
+gg config set show_path true
+```
+
 ## Update all dirty work repos
 
 ```bash
 gg -g work --only-dirty pull --ff-only
 ```
 
+## Drop or include an entire directory tree
+
+```bash
+# exclude every selected repo under foundation/
+gg -g oss --exclude ~/code/oss/foundation list
+
+# only repos under that directory
+gg --root ~/code --in ~/code/oss/foundation list
+```
+
 ## Enroll new learning / OSS checkouts
 
 ```toml
@@ -66,3 +86,12 @@ gg --dry-run init --profile default ./scratch
 ```bash
 gg --dry-run --timing status -sb
 ```
+
+## Upgrade Homebrew when PATH has a Cargo `gg`
+
+```bash
+brew update && brew upgrade git-gist
+which -a gg
+# If ~/.cargo/bin/gg wins, either reorder PATH or:
+# cargo uninstall git-gist
+```

docs/src/install.md

@@ -1,24 +1,39 @@
 # Install
 
-## Cargo (crates.io / git)
-
-```bash
-cargo install git-gist --locked
-# or from this repo:
-cargo install --git https://github.com/chtnnh/git-gist --locked
-cargo install --path . --locked
-```
-
 ## Homebrew
 
 ```bash
-brew tap chtnnh/tap
+brew tap chtnnh/tap          # first time
 brew install git-gist
 # or: brew install chtnnh/tap/git-gist
 ```
 
 Requires [`chtnnh/homebrew-tap`](https://github.com/chtnnh/homebrew-tap). On Homebrew 6+, you may need `brew trust chtnnh/tap` once.
 
+Upgrade later:
+
+```bash
+brew update && brew upgrade git-gist
+gg version
+```
+
+If `gg version` still shows an older build after upgrading, another `gg` may be earlier on your `PATH` (often `~/.cargo/bin/gg` from `cargo install`). Check with:
+
+```bash
+which -a gg
+```
+
+Prefer the Homebrew binary, reorder `PATH`, or `cargo uninstall git-gist` if you no longer need the Cargo install.
+
+## Cargo (crates.io / git)
+
+```bash
+cargo install git-gist --locked
+# or from this repo:
+cargo install --git https://github.com/chtnnh/git-gist --locked
+cargo install --path . --locked
+```
+
 ## Nix
 
 ```bash

docs/src/introduction.md

@@ -13,11 +13,13 @@ Design pillars:
 
 ## What’s in 1.2.0
 
-- Faster status probes and `--only-*` filters (fewer git spawns; see `benches/PROBE_PERF.md`)
+- Faster status probes and `--only-*` filters (fewer git spawns; maintainers: `benches/PROBE_PERF.md`)
 - `show_path` / `--show-path` — human tables print `name (path)`
 - Selection fixes: depth-aware under-root aliases, directory `--exclude`/`--in`, clearer passthrough flag-order errors
 - mdBook docs, `./scripts/ci.sh`, and reproducible `scripts/bench.py`
 
+See [Install](./install.md) for Homebrew upgrade / `PATH` shadowing notes, and [Targeting & flags](./targeting.md) for selection behavior.
+
 ## What’s in 1.1.0
 
 - Semantic colors in `overview` / `sync` / `stale` tables (tree, age, ahead/behind)

docs/src/packaging.md

@@ -22,8 +22,11 @@ Tap: [`chtnnh/homebrew-tap`](https://github.com/chtnnh/homebrew-tap). cargo-dist
 ```bash
 brew tap chtnnh/tap
 brew install git-gist
+brew update && brew upgrade git-gist
 ```
 
+After upgrading, if `gg version` is stale, check `which -a gg` — a Cargo install under `~/.cargo/bin` often shadows Homebrew. See [Install](./install.md).
+
 ### Debian / RPM
 
 Attached by [`.github/workflows/packages.yml`](../../.github/workflows/packages.yml) after a Release is published. Locally: `cargo deb` / `cargo generate-rpm` (metadata in `Cargo.toml`).
@@ -47,4 +50,4 @@ Optional later: nixpkgs / NUR PRs.
 4. Verify Release assets (archives + installers)
 5. Confirm Homebrew tap formula updated
 6. `cargo publish`
-7. Smoke-test: `brew upgrade git-gist`, installer script, `nix run`, `gg version`
+7. Smoke-test: `brew upgrade git-gist`, `which -a gg`, installer script, `nix run`, `gg version`

docs/src/quickstart.md

@@ -15,13 +15,35 @@ Scope to the current directory (honors `--root`; does not pull in out-of-root al
 gg ov --root .
 ```
 
+Show paths next to repo names (useful when basenames collide):
+
+```bash
+gg --show-path ov
+# or permanently:
+gg config set show_path true
+```
+
+Shallow discovery / drop a whole subtree:
+
+```bash
+gg --root ~/code --depth 2 --refresh list
+gg -g work --exclude ~/code/legacy list
+```
+
 Enroll new repos from watch rules in config:
 
 ```bash
 gg update --dry-run
 gg update
 ```
 
+Global flags go **before** a passthrough git verb:
+
+```bash
+gg --dry-run status -sb    # good
+# gg status --dry-run      # errors with a hint
+```
+
 Generate completions:
 
 ```bash

packaging/README.md

@@ -27,11 +27,13 @@ Tap repo: [`chtnnh/homebrew-tap`](https://github.com/chtnnh/homebrew-tap)
 ```bash
 brew tap chtnnh/tap   # first time; may need `brew trust chtnnh/tap` on Homebrew 6+
 brew install git-gist
+brew update && brew upgrade git-gist   # later versions
 ```
 
 - **v1.0.0 bootstrap:** source-build formula in the tap (historical).
 - **v1.1.0+:** cargo-dist overwrites `Formula/git-gist.rb` with a bottle/prebuilt formula (`tap = "chtnnh/homebrew-tap"` in `dist-workspace.toml`).
 - Requires repo secret `HOMEBREW_TAP_TOKEN` (PAT with Contents write on `chtnnh/homebrew-tap`).
+- After `brew upgrade`, if `gg version` is stale, check `which -a gg` — `~/.cargo/bin/gg` often shadows Homebrew.
 
 Template / fallback source formula: [`packaging/homebrew/git-gist.rb`](homebrew/git-gist.rb) (kept in sync for operators who build from source).