# macOS GCM Setup

Use this reference only on macOS.

## Verify

```bash
git --version
git-credential-manager --version
git config --show-origin --get-all credential.helper
```

Treat `command not found` as missing or broken even when Homebrew says the cask is installed.

If the version command succeeds, GCM is already available. Do not run Homebrew install, reinstall, or upgrade commands; continue to configuration and repository work.

## Install or Repair

Run the preferred installation only when the version command confirms that no working GCM exists:

```bash
brew install --cask git-credential-manager
```

If Homebrew records the cask but the command is unavailable:

```bash
brew reinstall --cask git-credential-manager
git-credential-manager --version
```

The package installer may require a macOS administrator password. Never ask the user to send that password. Have the user enter it in their own terminal or the macOS installer. If installation cannot be completed, stop rather than silently switching away from GCM.

If reinstall succeeds but the shell still cannot find the command, start a new shell and check:

```bash
command -v git-credential-manager
ls -l /usr/local/share/gcm-core/git-credential-manager
```

Use the reported installed path to diagnose PATH configuration; do not create speculative symlinks.

## Configure

```bash
git-credential-manager configure
git config --global --get-all credential.helper
```

GCM uses the macOS Keychain as its default secure credential store. Remove a repository-local helper override only after inspecting its origin and confirming it conflicts with GCM:

```bash
git config --show-origin --get-all credential.helper
git config --local --unset-all credential.helper
```

Do not replace GCM with `osxkeychain` when the requested workflow is standardized on GCM.

Official references: [GCM installation](https://github.com/git-ecosystem/git-credential-manager/blob/main/docs/install.md) and [credential stores](https://github.com/git-ecosystem/git-credential-manager/blob/main/docs/credstores.md).