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

> git config --local writes settings into a single repo’s .git/config. Reference for per-repo identity, scope precedence, and the not-in-a-repo error in CI.

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

git config --local stores settings that apply only to the current repository.

Use local config to scope a bot identity, credential, or option to one checkout without leaking it to the whole runner. Local always wins over global and system.

## What it does

git config --local reads and writes the repository config at .git/config, which takes precedence over --global and --system for that repository only.

## Common usage

```Terminal
git config --local user.email "bot@example.com"
git config --local core.autocrlf false
git config --local --get remote.origin.url
git config --local --list
```

## Options

| Flag | What it does |
| --- | --- |
| --local | Use the repository .git/config (default in a repo) |
| --get <key> | Read a value |
| --unset <key> | Remove a value |
| --list | Show settings from this scope |
| --show-origin | Reveal which file a value comes from |

## Common errors in CI

fatal: --local can only be used inside a git repository - you ran it before cloning or in the wrong directory. Remember precedence: local overrides global, so a stray local user.email shadows the global one; use --show-origin to find which file a surprising value lives in.

## 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 --local: Usage, Options & Common CI Errors?

Use local config to scope a bot identity, credential, or option to one checkout without leaking it to the whole runner. Local always wins over global and system.

### What it does?

git config --local reads and writes the repository config at .git/config, which takes precedence over --global and --system for that repository only.

### Common errors in CI?

fatal: --local can only be used inside a git repository - you ran it before cloning or in the wrong directory. Remember precedence: local overrides global, so a stray local user.email shadows the global one; use --show-origin to find which file a surprising value lives in.

---

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