Git's Magic Files

Andrew Nesbitt catalogs the committed files that control how git behaves for everyone who clones a repository. Unlike .git/ configuration, these files travel with the code and take effect automatically.

The core seven

.gitignore is the one everyone knows — pattern-based exclusion of untracked files. Git evaluates ignore rules from multiple locations: per-directory .gitignore files, .git/info/exclude for local-only patterns, and a global ignore file. The ** glob matches nested directories. One common gotcha: .gitignore only affects untracked files. If a file is already tracked, adding it to .gitignore does nothing until you git rm --cached it.

.gitattributes does far more than most teams realize. It configures LFS filters (*.psd filter=lfs diff=lfs merge=lfs), line ending normalization (*.sh text eol=lf), merge strategies (package-lock.json merge=ours to auto-resolve lockfile conflicts), and GitHub Linguist overrides (vendor/* linguist-vendored to exclude vendored code from language stats). Marking files as binary prevents git from attempting diffs or three-way merges on them.

.mailmap maps messy author identities to canonical ones. If someone committed under three different email addresses, mailmap collapses them into one for git log, shortlog, and blame. GitHub's contributor graphs ignore mailmap, though, so duplicates persist in the web UI.

.git-blame-ignore-revs lists commits that git blame should skip — the classic use case is a bulk formatting run that touches every file but changes no logic. GitHub, GitLab (since 15.4), and Gitea read this file automatically. Locally you need git config blame.ignoreRevsFile .git-blame-ignore-revs.

.gitmodules is created automatically by git submodule add and defines where submodule repos live and which branch to track.

.lfsconfig stores Git LFS endpoint URLs and transfer settings so LFS works without per-clone configuration.

.gitmessage is a commit message template, but unlike the others it requires manual setup (git config commit.template .gitmessage) per clone — it won't activate just by being in the repo.

Forge-specific folders

Each git forge has its own config directory for CI workflows, issue templates, and CODEOWNERS: .github/, .gitlab/, .gitea/, .forgejo/, .bitbucket/. The interesting bit is the fallback chains — Forgejo checks .forgejo/ then .gitea/ then .github/, and Gitea checks .gitea/ then .github/. SourceHut skips the folder convention entirely and uses .build.yml at the root.

Minor conventions

.gitkeep is a community convention (not a git feature) to force-track empty directories. .gitconfig files in repos are suggested configs that developers manually include — git won't auto-load them for security reasons. .gitsigners tracks trusted GPG/SSH signing keys. .gitreview configures Gerrit integration. .gitlint configures commit message linting.

Nesbitt also notes that Jujutsu (.jj/) coexists with .git/ and respects all of these magic files.

Advice for tool authors

If you're building tools that traverse git repos, respect the magic files: read .gitignore when walking the tree, check .gitattributes to identify binary/vendored/generated files, use .mailmap for author info, and handle .gitmodules for submodules. Git's config format ([section "subsection"] key = value) has parsers available in most languages through their git libraries.

Related conventions outside git

.editorconfig standardizes indentation and line endings across editors. Language version files (.ruby-version, .node-version, .python-version, .tool-versions) tell version managers which runtime to use. .dockerignore uses the same syntax as .gitignore but applies to Docker build contexts.

For a different angle on git internals — querying the full commit/blob/path history with SQL rather than config files — see linux-kernel-pgit and pgit. For tooling that rewrites that history safely rather than reading it, see git-history-command.