Unlock Git’s Hidden Power: Master the Magic Files That Control Your Repository

Overview

Git reads special files stored in a repository to control its own behavior. Unlike the local .git/ configuration, these files are version‑controlled, so every clone inherits the same settings. Tools that interact with Git (e.g., git-pkgs) should respect them.

.gitignore

Defines patterns for files that Git must never track. Each line is a pattern supporting wildcards ( *), directory markers ( /), negation ( !pattern) and recursive matching ( **). Example:

node_modules/
*.log
.env
dist/

Git checks ignore files in this order:

Per‑directory .gitignore Local .git/info/exclude Global file referenced by core.excludesFile (e.g. ~/.config/git/ignore)

Global ignores are useful for OS‑specific files such as .DS_Store or Thumbs.db. The file only affects untracked files; to stop tracking a file that is already in the index, run git rm --cached <path>.

.gitattributes

Controls how Git treats specific paths. It can set filters, diff drivers, merge drivers, line‑ending normalization and language‑detection overrides. Example:

# Clean/smudge filters
*.psd filter=lfs diff=lfs merge=lfs

# Line ending normalization
*.sh text eol=lf
*.bat text eol=crlf

# Binary files
*.png binary

# Custom diff driver
*.json diff=json

# Merge strategy (keep local version on conflict)
package-lock.json merge=ours

# GitHub Linguist overrides
vendor/* linguist-vendored
*.gen.go linguist-generated
docs/* linguist-documentation

Key attributes: text – normalizes line endings. binary – disables diff/merge. merge=ours – always keep the local version during a conflict.

GitHub’s Linguist reads .gitattributes to apply linguist‑vendored, linguist‑generated or linguist‑documentation flags.

.lfsconfig

Repository‑level configuration for Git LFS. It uses the same syntax as git config. Example:

[lfs]
    url = https://lfs.example.com/repo
[lfs "transfer"]
    maxretries = 3

When LFS commands run, Git reads this file so all collaborators share the same LFS server URL and transfer options. After adding LFS patterns, rewrite history with git lfs migrate to move existing large files into LFS.

.gitmodules

Configuration for submodules. Adding a submodule with git submodule add writes an entry like:

[submodule "vendor/lib"]
    path = vendor/lib
    url = https://github.com/example/lib.git
    branch = main

The file must reside at the repository root. Submodules are not fetched by default; use git submodule update --init --recursive or clone with --recurse-submodules. Each submodule records a specific commit (not a version range) and creates a nested .git/ directory.

.mailmap

Maps author names and email addresses to a canonical identity, affecting the output of git log, git shortlog and git blame. The format is:

Canonical Name <canonical@email> Commit Name <commit@email>

Example (email addresses are escaped to avoid HTML parsing):

# Map old email to new email
Jane Developer <[email protected]> <[email protected]>

# Standardize name spelling
Jane Developer <[email protected]> Jane Dev <[email protected]>

# Fix both name and email
Jane Developer <[email protected]> <[email protected]>
Jane Developer <[email protected]> J Developer <[email protected]>

Git automatically applies the mapping when displaying author information. GitHub’s contributor graph does not honor .mailmap.

.git-blame-ignore-revs

Lists commit SHA‑1s that git blame should skip, useful for bulk formatting or lint‑fix commits. Example:

# Ran prettier on entire codebase
a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

# Migrated to ESLint flat config
b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1

Enable it with:

git config blame.ignoreRevsFile .git-blame-ignore-revs

GitHub, GitLab (≥ 15.4) and Gitea read this file automatically.

.gitmessage

Template for commit messages. Configure with: git config commit.template .gitmessage Because the template must be set after cloning, many projects prefer a commit‑msg hook instead.

Platform‑Specific Magic Directories

Hosting services define their own configuration directories that keep CI/CD workflows, issue templates, CODEOWNERS, etc., out of the repository root. Common directories are:

.github/

.gitlab/

.forgejo/

.gitea/

.bitbucket/

Forgejo searches .forgejo/ → .gitea/ → .github/ while Gitea searches .gitea/ → .github/, allowing platform‑specific overrides.

Other Conventional Dot Files

.gitkeep – placeholder to keep empty directories (Git does not track empty directories).

.gitconfig – optional repository‑wide config that must be included manually via git config include.path.

.gitsigners – lists trusted GPG/SSH keys for signed commits (used with gpg.ssh.allowedSignersFile).

.gitreview – Gerrit code‑review configuration; git review reads it to push to a Gerrit server.

.gitlint – configuration for the gitlint commit‑message linter.

Beyond Git

Similar “dot‑file” conventions exist for other tools:

.editorconfig – defines editor settings (indentation, line endings, charset, etc.).

.ruby-version , .node-version , .python-version – specify the language version for version managers such as rbenv, nodenv, pyenv, nvm or asdf.

.tool-versions – asdf’s multi‑language version file.

.dockerignore – works like .gitignore but for Docker build contexts, preventing unwanted files from being sent to the Docker daemon.

Practical Guidance for Tool Developers

When traversing a repository, read .gitignore to know which files to skip.

Parse .gitattributes to detect binary, generated or vendor files.

Use .mailmap to present unified author information.

Read .gitmodules when handling submodule operations.

For full syntax details, refer to the official Git documentation linked in the original article.