Skip to main content

Manage Auto-Detect

Manage gpx configuration settings, such as enabling or disabling the auto-detect feature.

Usage​

gpx config <get|set> <key> [value]

Available Keys​

KeyDescriptionDefault
auto-detectAutomatically switch local profile when entering a repofalse

Examples​

Check a setting​

gpx config get auto-detect

Expected output:

auto-detect = false

Change a setting​

gpx config set auto-detect true

How Auto-Detect Works​

When auto-detect is enabled, gpx automatically switches your local profile whenever you cd into a repository that uses a gpx SSH host alias (e.g., github.com-work) in its remote URL.

Setup​

  1. Enable auto-detect: 
    gpx config set auto-detect true
  2. Initialize shell hooks (if not already done): 
    gpx init --shell zsh

What happens behind the scenes​

When you move into a repository:

cd ~/work/company-repo

The shell hook fires and does the following:

  1. Checks the repo's remote URL (e.g., git@github.com-work:org/repo.git).
  2. Extracts the profile name ("work") from the SSH host alias.
  3. Automatically sets the local profile to work (equivalent to running gpx use work --local).
  4. Updates the terminal prompt badge.
NOTE

Auto-detect only changes the local profile for the current repository. Your global profile remains unchanged.

Auto-detect and Commit Guard​

Auto-detect and Commit Guard are designed to work perfectly together:

  • Auto-detect ON: The correct local profile is set automatically when you enter a repo. The Commit Guard silently verifies the match and lets your commits through.
  • Auto-detect OFF: You must manually switch profiles with gpx use <name> --local. If you forget, the Commit Guard catches the mismatch and blocks the commit, keeping your repository safe.
  • gpx init - Install the shell hooks required for auto-detect to work.