Use Case 1: Identifying Files as Binary

This one is fairly simple. To tell Git that a file is binary, simply set the binary attribute in the Git attributes file. For example, *.exe binary . Binary here actually corresponds to the deprecated settings of -crlf and -diff. So, if you think about the dash (-) on the front of those attributes as meaning don't do it, you could interpret binary as don't try to convert or fix eol issues (-crlf) and don't try to execute or print a diff (-diff) for executable files.

Use Case 2: Specifying Handling for Line Endings

In this case, you have several attributes to choose from:

• text—This attribute has to do with line normalization and indicating text file types. Here are some examples of how it can be specified, along with their meanings.
  • text (setting the value) tells Git to normalize line endings and that files like this are text files.
  • -text (unsetting the value) tells Git not to attempt to normalize line endings.

  • text=auto (set to value) tells Git to normalize line endings if it thinks the file is text. (To determine this, Git is checking for a NULL value in a significant part of the file. If the NULL value is found, the file is considered to be binary.)

    If text is not specified, then Git falls back to using the core.autocrlf value as configured by the user.

• eol—This attribute tells Git which style of line normalization to apply. Its presence tells Git that this is a text file.
  • eol=crlf (set to value)—llike autocrlf=true, this value tells Git to normalize files (to just LF) at add or commit, and insert CRLFs on checkout.
  • eol=lf (set to value)—like autocrlf=input, this value tells Git to normalize files (to just LF) at add or commit, and leave as LFs on checkout.

Use Case 3: Creating a Custom Filter

If you simply define the attribute as filter=<name>, Git assumes you are defining a custom filter called <name>. This allows you to have two filtering actions, known as smudge and clean.

Smudge is essentially a way to say, “For the matching items in the Git attributes file, run a set of code (a filter) when those items are checked out of Git.” Clean is the same, but it runs designated code when the matching items are committed back into Git. Figure 10.1 shows where these actions fit into your Git model.

Git assumes that the name you provide to the filter actually refers to a filter driver. A filter driver is a program or set of commands that are defined to execute for the smudge and clean operations when this filter is run. To map the filter names to the actual code that is executed, you just use the standard git config operation.

Let's take a look at a simple example to illustrate how all of this works. Suppose you have a couple of HTML files that you use as a header and footer across multiple divisions in your company. They contain a placeholder in the form of the text string %div to indicate where the proper division name should be inserted.

You want to use the smudge and clean filters to automatically replace the placeholder with your division name (ABC) when you check the file out of Git, and make sure to set it back to the generic version if you make any other changes and commit those changes.

The following listing shows my two source files:

$ cat div_test_header.html
<H1>Running tests for division:%div</H1>

$ cat div_test_footer.html
<H1>Division:%div testing summary</H1>

To make the appropriate transformations, I'm going to create a custom filter that will have associated clean and smudge actions. I'll call this custom filter insertDivisionABC.

This filter will simply use the sed command to substitute ABC for %div, or vice-versa, as required. To define this filter and its actions for Git, you can use the config command as follows:

$ git config filter.insertDivisionABC.smudge "sed 's/%div/ABC/'"
$ git config filter.insertDivisionABC.clean "sed 's/ision:ABC/ision:%div/'"

These commands say, “When you check out these files, replace the occurrence of %div with ABC. And, if you commit a changed version of this file, set it back to the generic form (with the %div) where you had ABC.” (I include a part of division here in the replacement string just to be more precise.)

With this form of the config command, the parts after git config are organized as [item class, item name, subitem, subitem value]. So, if you were to look at the actual config file after these commands, you would find the following section:

$ cat .git/config
       …
 [filter "insertDivisionABC"]
        smudge = sed 's/%div/ABC/'
        clean = sed 's/ision:ABC/ision:%div/'

The last part of connecting everything together is to create a (or append to an existing) Git attributes file with a line that tells Git to run your filter for files matching the desired pattern. The simplest kind of file would be one such as created by the following command:

$ echo "div*.html filter=insertDivisionABC" > .gitattributes

The presence of a .gitattributes file with the line div*.html filter=insertDivisionABC tells Git, “For files matching the pattern, run the specified filter.” This then points to the commands you have configured, depending on whether a checkout or add is being done.

After a checkout with the attributes file and the filter is in place, your local file contents would look like the following output:

$ cat div_test_header.html
<H1>Running tests for division:ABC</H1>

$ cat div_test_footer.html
<H1>Division:ABC testing summary</H1>

Suppose that you now make changes to the local files, adding the text full in one and all in the other. A diff will take into account the filter and just show you the differences without the substitution being applied.

$ git diff
diff --git a/div_test_footer.html b/div_test_footer.html
index 8a5bb93..60e32b7 100644
--- a/div_test_footer.html
+++ b/div_test_footer.html
@@ -1 +1 @@
-<H1>Division:%div testing summary</H1>
+<H1>Division:%div full testing summary</H1>
diff --git a/div_test_header.html b/div_test_header.html
index 124625e..fd1aeb6 100644
--- a/div_test_header.html
+++ b/div_test_header.html
@@ -1 +1 @@
-<H1>Running tests for division:%div</H1>
+<H1>Running all tests for division:%div</H1>

If you now add the files, a status command shows them as staged and modified.

$ git add div*.html

$ git status
On branch feature
Changes to be committed:
  (use "git reset HEAD <file>…" to unstage)

        modified:   div_test_footer.html
        modified:   div_test_header.html

A diff command shows no differences. If you cat the local versions of the files, they still show the substitution from the smudge.

$ git diff


$ cat div_test_footer.html
<H1>Division:ABC full testing summary</H1>

$ cat div_test_header.html
<H1>Running all tests for division:ABC</H1>

You know that the clean filter should have removed your substitution, but the question is, “How do you verify that?” There is a trick you can use with the show command to see the version in the staging area—show :0:<filename>. Using this command, you can verify that the clean filter was applied when the files were staged.

$ git show :0:div_test_footer.html
<H1>Division:%div full testing summary</H1>

$ git show :0:div_test_header.html
<H1>Running all tests for division:%div</H1>

Use Case 4: Tricking Git Merge into Ignoring Files or Paths

For this use case, you can use a trick to tell Git not to merge a file or path when a merge operation is run on the larger set of files. This is not necessarily a common, intended use case, but it can be very useful and illustrates how to use filters on attributes to accomplish custom tasks.

Another type of attribute available in the Git attributes file is merge. Normally, the merge attribute, if specified, is resolved to text or binary. However, using a filter in another way, you can specify a program or command to run when the merge attribute is specified. Normally, handling the merge filter would be similar to defining a custom mergetool (see Chapter 9) that expects certain arguments and performs certain behaviors.

For your purposes here, though, you just need to specify a tool or command that returns a value of true. This is because Git expects any kind of merge filter like this to return true to indicate that the custom merge behavior was successful and you are done. Another characteristic of the merge filter implementation is that when the merge has been completed, the result is stored in the original filename. So, if you just return true here, this is effectively a NO-OP as far as changing the file is concerned. However, Git thinks it has done its job and processed this file as part of the merge.

To set this functionality up, in the Git attributes file, you can define a custom filter for the merge attribute to use. One common name that is often used for this purpose is ours to correspond with the merge option for the recursive strategy and the Ours strategy. For your purposes here, to be a little clearer, you'll use the name unchanged.

Then, to make this all work, you set a configuration value that tells Git to define a filter driver for the merge attribute value of unchanged. This filter driver just has to return true (assuming you have a true command available on your system). The command to configure this value would look like this:

$ git config [--global] merge.unchanged.driver true

Then, in your Git attributes file, you can just specify merge=unchanged for the file or path.

$ cat .gitattributes
filename.ext merge=unchanged

When Git is running a merge that includes this file or path, it assumes from the attributes file that it should run the filter program named unchanged, which then just evaluates to true. Git is done at that point, and so the file or path is not changed.

Note that this trick depends on a particular configuration that needs to be shared and set if other users will use this Git attributes file in this way.

Other Attributes

There are other attributes I haven't covered that are available to use in a Git attributes file. Two attributes that you may encounter are ident and diff:

• ident—This attribute causes a substitution to occur if the string $Id$ is found in a file on checkout. In other source management systems, this kind of substitution results in items like userids, dates, and so on being substituted. In Git, this is less useful because the string is just expanded to include the SHA1 value as $Id: <sha1 value> $. On checkin, the substitution is reverted.
• diff—This attribute describes how diffs are generated for the matching file or file types. In short, if it is set (diff), the diff is generated as text. If it is unset (-diff), it is treated as a binary file when a diff is attempted. If it is unspecified, then the default diff behavior is performed. And if it is set to a string, that string is treated as a filter driver that can be defined to do whatever operations are desired when a diff for the matching files or file type is invoked.

Example File

Combining all of these attributes into an example Git attributes file might look like this:

$ cat .gitattributes
# Default is to detect text files and perform normalization to LF
* text=auto

# Treat exe files as binary
*.exe binary

# Don't insert CRLFs in our sh files
*.sh -crlf

# Set eol sequence to CRLF for *.txt files
*.txt eol=crlf

# Don't merge our home page file
index.html merge=unchanged

# Use our custom smudge and clean filters for these files
div*.html filter=insertDivisionABC

# Update text files in the misc directory
misc/*.txt filter=change_text

Note that you have the text=auto attribute setting for everything as your first entry. This acts as a sensible default for normalizing files that Git detects as text. This setting can be overwritten for specific files and file types by later entries in the file.

The last entry here is one I didn't use in the text. However, it illustrates the idea that subdirectory paths can be used to restrict attributes. In this case, the change_text filter will be applied to files with the .txt extension, but only files in the misc subdirectory. Files with the same extension in other subdirectories will not have the filter applied.

Use Cases for Pattern Negation

At first glance, the idea of pattern negation might seem strange in a Git ignore file. If you are going to include the file, why list it and negate it instead of just not putting it in the ignore file in the first place?

There are two typical uses for this format. One is to override a more general exclusion in a specific path, and the other is to allow targeted inclusion in cases where you want to exclude most other items.

$ git config --list --global | grep excludes
core.excludesfile=/Users/dev/.config/git/ignore

$ cat /Users/dev/.config/git/ignore
# Ignore bak files no matter where in the tree
*.bak

$ cat /Users/dev/myrepo/.git/info/exclude
# Track *.bak files for this repository
!*.bak

myrepo
│   .gitignore
│
└———subdir1
    │   filea.txt
    │   fileb.txt
    │
    └———subdir2
            file1.txt
            file2.txt

$ cat .gitignore
# ignore all of the things under this directory
subdir1/*
# except for this child directory
!subdir1/subdir2
# but ignore everything under it
subdir1/subdir2/*
# except for this file
!subdir1/subdir2/file1.txt

$ git add

$ git status
On branch master

Initial commit

Changes to be committed:
  (use "git rm --cached <file>…" to unstage)

        new file:   .gitignore
        new file:   subdir1/subdir2/file1.txt