gpx (Git Profile Extension) helps you switch Git/SSH identities between projects.

• Install from crates.io:

  cargo install gpx-cli
  gpx --help

• Build from source:

  cargo build --release
  ./target/release/gpx --help

• Initialize GPX files and bootstrap config:

  gpx init

• Remove GPX-managed bootstrap/cache/state when needed (and prune empty GPX root dirs):

  gpx deinit

• Inspect which profile matches the current directory:

  gpx check

• Apply the selected profile now:

  gpx apply

• See current status and diagnostics:

  gpx status --verbose
  gpx doctor

• List available profiles/rules:

  gpx list profiles
  gpx list rules

• Run zero-persistence passthrough commands (gpx git and no-subcommand mode):

  gpx git -p work -- fetch
  gpx -p work -- cat ~/.gitconfig
  gpx -- git status

• Run gpx init first.
• If no config exists, GPX creates a commented template config.toml for you.
• Edit config.toml to define your profiles and matching rules.
• Run gpx check and gpx apply to verify and activate.

• [core].defaultProfile: Required no (but required if no rule can match); Default unset; Allowed profile name.
• [core].ruleMode: Required no; Default first-match; Allowed first-match | highest-score.
• [core].mode: Required no; Default global-active; Allowed global-active | repo-local.
• [hook].fixPolicy: Required no; Default continue; Allowed continue | abort-once.
• [run].allowProfileOverride: Required no; Default false; Allowed true | false.
• [worktree].allowSharedFallback: Required no; Default false; Allowed true | false.
• [ssh].dynamicMatch: Required no; Default false; Allowed true | false.
• [rule.<name>]: Required yes for automatic switching; profile is required and at least one matcher is required from match.path | match.remoteHost | match.remoteOrg | match.fileExists.

Hook installation is command-driven (gpx hook install/uninstall ...) and no longer uses config toggles like hook.shell or hook.git.

You can enable automatic profile updates with shell and/or Git hooks.

• Install shell hook:

  gpx hook install --shell zsh

• Install Git hook:

  gpx hook install --git

• Install both:

  gpx hook install --shell zsh --git

• Uninstall hooks:

  gpx hook uninstall --shell zsh
  gpx hook uninstall --git

Supported shells: bash, zsh, fish, nushell, tcsh, elvish.

gpx init
gpx deinit
gpx doctor
gpx status [--verbose]
gpx list [profiles|rules] [--json]
gpx check [--cwd <path>] [--json]
gpx apply [--cwd <path>] [--profile <name>] [--dry-run]
gpx hook install [--shell bash|zsh|fish|nushell|tcsh|elvish] [--git]
gpx hook uninstall [--shell bash|zsh|fish|nushell|tcsh|elvish] [--git]
gpx git [-p <name>|--profile <name>] -- <git args...>
gpx [-p <name>|--profile <name>] -- <command args...>

For full config reference and behavior details, see docs/SPEC.md.