The benefits of git attributes and how to set them up

Git .attributes file

Git attributes files

If you are a Git user, you may have encountered situations where Git does not behave as expected.

For example, maybe Git tries to merge binary files that are not meant to be merged, or maybe it shows unreadable diffs for non-text files, or maybe it messes up with line endings when you work across different platforms. These problems can be frustrating and time-consuming to fix, but fortunately, there is a way to avoid them: using a git attributes file.

A git attributes file is a simple text file that gives attributes to pathnames. Each line in the git attributes file is of the form:

pattern attr1 attr2 …

That is, a pattern followed by an attributes list, separated by whitespaces. The pattern can be a file name, a directory name, or a wildcard expression that matches multiple paths. The attributes are key-value pairs that tell Git how to handle those paths.

You can place a git attributes file in one of these locations:

• In the $GIT_DIR/info/attributes file (which has the highest precedence), if you want to apply the attributes only to your local repository and not share them with others.
• In the .gitattributes file in any directory of your working tree (the further the directory that contains .gitattributes is from the path in question, the lower its precedence), if you want to version-control and distribute the attributes with your project.
• In a file specified by the core.attributesFile configuration option (see git-config), if you want to apply the attributes globally for all your repositories.

Using git attributes, you can do things like:

• Specify separate merge strategies for individual files or directories in your project. For example, you can tell Git always to use binary merge for image files, or always use union merge for changelogs.
• Tell Git how to diff non-text files. For example, you can tell Git to convert your binary data to a text format that can be compared via the normal diff, such as using pandoc for Word documents or ExifTool for images.
• Have Git filter content before you check it into or out of Git. For example, you can tell Git to remove trailing whitespace from your source code files before committing them or replace specific placeholders with dynamic values when checking out.

In this blog post, I will show you some examples of using git attributes for common scenarios.

Example 1: Marking binary files

Some files look like text files but are actually binary data that should not be merged or diffed by Git. For instance,.pbxproj files used by Xcode projects on macOS are JSON datasets written out by the IDE that records your build settings and other information. Although they are technically text files (because they are UTF-8 encoded), they are really lightweight databases that cannot be merged or diffed meaningfully.

To tell Git to treat all pbxproj files as binary data, add the following line to your .gitattributes file:

*.pbxproj binary

Now, Git won’t try to convert or fix line endings issues; nor will it try to compute or print a diff for changes in this file when you run git show or git diff on your project.

Example 2: Diffing Word documents

If you want to version-control Word documents (.docx files), you can stick them in a Git repository and commit occasionally; but what good does that do? If you run git diff normally, you only see something like this:

$ git diff diff — git a/chapter1.docx b/chapter1.docx index 88839c4..4afcb7c 100644 Binary files a/chapter1.docx and b/chapter1.docx differ

This is not very helpful if you want to see what actually changed in your document. However, you can use git attributes to tell Git how to convert your Word document into a plain text format that can be compared via the standard diff algorithm. One tool that can do this conversion is pandoc, a universal document converter.

To tell Git to use pandoc for diffing docx files, add these lines to your .gitattributes file:

*.docx diff=pandoc [diff “pandoc”] textconv=pandoc — to=markdown prompt = false

The first line tells Git to use an attribute called “pandoc” for diffing docx files. The second and third lines define what this attribute does: it runs pandoc with the — to=markdown option to convert docx files into markdown format, and it disables prompting when running external commands.