Last updated September 30, 2016.
Where do I start?
.gitconfig file for your user account:
- On Unix-like systems (OS X, Linux, BSD), check
- On Windows, check
If the file does not exist yet, create it.
(If the directory does not exist, search harder.)
You can also open or create it in your default terminal editor via git using the command:
git config -e --global
Within a git repo, omitting the --global flag will allow you to edit the config for that specific repo.
How to I configure the .gitconfig file?
.gitconfig is a simple text file in .ini format. Open it in the text editor of your choice.
Add the following configuration directives:
- Always use Unix line-endings in checked out files
[core] autocrlf = false safecrlf = false
All code and patches will use Unix line-endings (LF) instead of Windows line-endings (CRLF). Unix line-endings are the common standard in open-source projects.
- Do not ignore letter casing in filenames on case-insensitive filesystems (like FAT on Windows)
[core] ignorecase = false
Note: Even with this setting, Git might not catch some file/directory renames. In those cases, the only workaround is:
git mv original original.tmp git mv original.tmp Original
- Automatically rebase when pulling
[branch] autosetuprebase = always
This setting prevents accidental "merge bubbles" (detailed explanation) and is recommended for working on Drupal.org projects. (You still can, and should, merge explicitly when adding large change sets; the purpose is just to prevent unintentional merges when pushing.)
- Use color highlighting for diffs and the git log
[color] ui = true
- Optimize diffs for renamed and copied files
[diff] renames = copies
When renaming or copying files,
git diffwill not show the entire file content for the rename/copy, but merely a single line denoting the rename/copy instead. Subsequent diff hunks in a patch may perform additional changes to the renamed/copied file. This keeps patches small.
git diff/format-patchsometimes may not adhere to
renames = copies. The actual limit is not documented, but git only checks for renames/copies up to a similarity of 50-70%. In order to enforce the renames/copies diff behavior, pass an explicit smaller limit:
git diff -M25%
Do not use values lower than 25%, since that will cause git to find false-positive matches on source files; i.e., "copying" a completely different file that just happens to be somewhere in the code-base.
Note: Patches involving renamed and/or copied files will be incompatible with patch file parsers that do not support this diff extension from git.
- Define alias properly for applying patches
[alias] a = apply --index
git a some.patchwill apply the patch and also add any new/renamed/copied/deleted files accordingly to git's index, so you do not forget to add them manually before committing the patch.
git am some.patch(built-in) applies a patch-set. A patch-set is a patch file that contains multiple patches, using a special format that looks similar to e-mail headers for each patch in the set.
git amonly works for patch-sets.
git aonly works for regular diffs.
- Define alias for creating a patch-set
[alias] p = format-patch --stdout
git p -1 > my.patchwill create a patch-set that contains the last commit from the current branch.
git p 8.x > my.patchwill create a patch-set that contains all commits from the current branch since 8.x.
Note: As of now, the common Drupal development workflow prefers regular
git diffpatches over patch-sets containing multiple commits. Patch-sets containing one commit are OK. Patch-sets with multiple commits are only used in edge-cases.
- Define the global
[core] excludesfile = ~/.gitignore
In addition to a project-specific
.gitignorefile in your working directory, git will take into account the
.gitignorefile in your user profile directory.
Create a ~/.gitignore file for 7.x or 8.x
# Patch/diff artifacts. *.patch *.diff *.orig *.rej interdiff*.txt # emacs artifacts. *~ \#*\# # VI swap file *.swp # Hidden files. .DS* .project # Windows links. *.lnk # Temporary files. tmp* # Exclude IDE's project directory nbproject .idea
Thus, git will ignore all .patch, .orig, .rej, .lnk and other files and dirs, everywhere. You can still force-add an ignored file by doing
git add -f my.patch, but you usually don't want to do that.
Complete ~/.gitconfig for Drupal 7.x or 8.x
[core] autocrlf = false safecrlf = false ignorecase = false excludesfile = ~/.gitignore [branch] autosetuprebase = always [diff] renames = copies [color] ui = true [alias] a = apply --index p = format-patch --stdout