Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Files and Formats

include and includeIf in Git config

Reference for include.path and includeIf in Git config: share settings between files, and apply them by directory (gitdir), branch (onbranch) or remote URL.

The [include] section pulls another file's settings into the current config file, as if they were pasted at that spot. [includeIf "<condition>"] does the same only when a condition holds, such as "this repository lives under ~/work/". It is how people keep one global config but use a different email address, signing key or proxy for work and personal projects.

Includes are resolved when Git reads the config, so git config --list shows the included values, and --show-origin tells you which file each came from.

Terminal
[include]
    path = ~/.gitconfig-shared
[includeIf "gitdir:~/work/"]
    path = ~/.gitconfig-work

Try it

Bash A plain include

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash includeIf by directory and by branch

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
[include]
    path = <file>
[includeIf "<condition>"]
    path = <file>
Condition Matches when
gitdir:<pattern> The repository's .git directory matches the glob pattern. A trailing / means /**.
gitdir/i:<pattern> Same, case-insensitive.
onbranch:<pattern> The current branch matches the glob (for example release/**).
hasconfig:remote.*.url:<pattern> Any remote URL matches the pattern (Git 2.36 and later).

Path rules: a relative path is relative to the file containing the directive (not to the working directory). ~/ expands to the home directory. Included files may include others, up to a depth limit of 10.

Edge cases: a missing include file is silently ignored. Patterns support *, ** and ?. gitdir matches against the real location of the git directory, so a symlinked path may need the target path or gitdir/i: on case-insensitive filesystems.

Usage notes

  • Order matters. Include contents are inserted where the directive appears. Put the [includeIf] after settings it should override, because the last value wins.
  • Paths must end in / for a directory match: gitdir:~/work/ covers every repository below ~/work.
  • gitdir is for the repository, not the cwd. A linked worktree or submodule matches on its own git directory.
  • Checks. git config --show-origin --get user.email proves which file won. Use git config --list --no-includes to see raw files.
  • Writing with git config modifies only the file you target (--global, --local); it never writes into an included file.
  • include.path is multi-valued. Add several path lines in one section.
  • Security. An included file can set any option, including ones that run commands, so only include files you trust.