# git config --global: Usage, Options & Common CI Errors

> git config --global sets user-wide Git settings in ~/.gitconfig. Reference for identity, safe.directory, and the missing-HOME and ownership errors in CI containers.

Source: https://latchkey.dev/learn/command-reference/git-config-global  
Updated: 2026-06-25

git config --global writes settings that apply to every repo for the current user.

CI jobs lean on global config to set a bot identity, default branch, and the safe.directory exceptions that newer Git requires inside containers.

## What it does

git config --global reads and writes the per-user config file (~/.gitconfig or $XDG_CONFIG_HOME/git/config), affecting all repositories run by that user.

## Common usage

```Terminal
git config --global user.name "CI Bot"
git config --global user.email "ci@example.com"
git config --global init.defaultBranch main
git config --global --add safe.directory /workspace
git config --global --list
```

## Options

| Flag | What it does |
| --- | --- |
| --global | Use the per-user config file |
| --add <key> <value> | Append a multi-valued key |
| --get <key> | Read a value |
| --unset <key> | Remove a value |
| --list | Show all effective settings |

## Common errors in CI

fatal: detected dubious ownership in repository at ‘<dir>’ - the checkout is owned by a different uid than the running user (common with Docker). Fix with git config --global --add safe.directory <dir>. If $HOME is unset, --global has nowhere to write; export HOME or use --file.

## Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

```.github/workflows/ci.yml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### git config --global: Usage, Options & Common CI Errors?

CI jobs lean on global config to set a bot identity, default branch, and the safe.directory exceptions that newer Git requires inside containers.

### What it does?

git config --global reads and writes the per-user config file (~/.gitconfig or $XDG_CONFIG_HOME/git/config), affecting all repositories run by that user.

### Common errors in CI?

fatal: detected dubious ownership in repository at ‘<dir>’ - the checkout is owned by a different uid than the running user (common with Docker). Fix with git config --global --add safe.directory <dir>. If $HOME is unset, --global has nowhere to write; export HOME or use --file.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt