precedence), `.gitattributes` file in the same directory as the
path in question, and its parent directories up to the toplevel of the
work tree (the further the directory that contains `.gitattributes`
-is from the path in question, the lower its precedence).
+is from the path in question, the lower its precedence). Finally
+global and system-wide files are considered (they have the lowest
+precedence).
If you wish to affect only a single repository (i.e., to assign
-attributes to files that are particular to one user's workflow), then
+attributes to files that are particular to
+one user's workflow for that repository), then
attributes should be placed in the `$GIT_DIR/info/attributes` file.
Attributes which should be version-controlled and distributed to other
repositories (i.e., attributes of interest to all users) should go into
-`.gitattributes` files.
+`.gitattributes` files. Attributes that should affect all repositories
+for a single user should be placed in a file specified by the
+`core.attributesfile` configuration option (see linkgit:git-config[1]).
+Attributes for all users on a system should be placed in the
+`$(prefix)/etc/gitattributes` file.
Sometimes you would need to override an setting of an attribute
-for a path to `unspecified` state. This can be done by listing
+for a path to `Unspecified` state. This can be done by listing
the name of the attribute prefixed with an exclamation point `!`.
smudge filter means that the clean filter _must_ accept its own output
without modifying it.
+Sequence "%f" on the filter command line is replaced with the name of
+the file the filter is working on. A filter might use this in keyword
+substitution. For example:
+
+------------------------
+[filter "p4"]
+ clean = git-p4-filter --clean %f
+ smudge = git-p4-filter --smudge %f
+------------------------
+
Interaction between checkin/checkout attributes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- `pascal` suitable for source code in the Pascal/Delphi language.
+- `perl` suitable for source code in the Perl language.
+
- `php` suitable for source code in the PHP language.
- `python` suitable for source code in the Python language.
manually with `git update-ref -d refs/notes/textconv/jpg` (where
"jpg" is the name of the diff driver, as in the example above).
+Choosing textconv versus external diff
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you want to show differences between binary or specially-formatted
+blobs in your repository, you can choose to use either an external diff
+command, or to use textconv to convert them to a diff-able text format.
+Which method you choose depends on your exact situation.
+
+The advantage of using an external diff command is flexibility. You are
+not bound to find line-oriented changes, nor is it necessary for the
+output to resemble unified diff. You are free to locate and report
+changes in the most appropriate way for your data format.
+
+A textconv, by comparison, is much more limiting. You provide a
+transformation of the data into a line-oriented text format, and git
+uses its regular diff tools to generate the output. There are several
+advantages to choosing this method:
+
+1. Ease of use. It is often much simpler to write a binary to text
+ transformation than it is to perform your own diff. In many cases,
+ existing programs can be used as textconv filters (e.g., exif,
+ odt2txt).
+
+2. Git diff features. By performing only the transformation step
+ yourself, you can still utilize many of git's diff features,
+ including colorization, word-diff, and combined diffs for merges.
+
+3. Caching. Textconv caching can speed up repeated diffs, such as those
+ you might trigger by running `git log -p`.
+
+
Marking files as binary
^^^^^^^^^^^^^^^^^^^^^^^
`merge`
^^^^^^^
-The attribute `merge` affects how three versions of a file is
+The attribute `merge` affects how three versions of a file are
merged when a file-level merge is necessary during `git merge`,
and other commands such as `git revert` and `git cherry-pick`.
Take the version from the current branch as the
tentative merge result, and declare that the merge has
- conflicts. This is suitable for binary files that does
+ conflicts. This is suitable for binary files that do
not have a well-defined merge semantics.
Unspecified::
By default, this uses the same built-in 3-way merge
- driver as is the case the `merge` attribute is set.
- However, `merge.default` configuration variable can name
- different merge driver to be used for paths to which the
+ driver as is the case when the `merge` attribute is set.
+ However, the `merge.default` configuration variable can name
+ different merge driver to be used with paths for which the
`merge` attribute is unspecified.
String::
Set::
Notice all types of potential whitespace errors known to git.
+ The tab width is taken from the value of the `core.whitespace`
+ configuration variable.
Unset::
Unspecified::
- Use the value of `core.whitespace` configuration variable to
+ Use the value of the `core.whitespace` configuration variable to
decide what to notice as error.
String::
Specify a comma separate list of common whitespace problems to
- notice in the same format as `core.whitespace` configuration
+ notice in the same format as the `core.whitespace` configuration
variable.
(See linkgit:git-config[1]).
-USING ATTRIBUTE MACROS
+USING MACRO ATTRIBUTES
----------------------
You do not want any end-of-line conversions applied to, nor textual diffs
------------
but that may become cumbersome, when you have many attributes. Using
-attribute macros, you can specify groups of attributes set or unset at
-the same time. The system knows a built-in attribute macro, `binary`:
+macro attributes, you can define an attribute that, when set, also
+sets or unsets a number of other attributes at the same time. The
+system knows a built-in macro attribute, `binary`:
------------
*.jpg binary
------------
-which is equivalent to the above. Note that the attribute macros can only
-be "Set" (see the above example that sets "binary" macro as if it were an
-ordinary attribute --- setting it in turn unsets "text" and "diff").
+Setting the "binary" attribute also unsets the "text" and "diff"
+attributes as above. Note that macro attributes can only be "Set",
+though setting one might have the effect of setting or unsetting other
+attributes or even returning other attributes to the "Unspecified"
+state.
-DEFINING ATTRIBUTE MACROS
+DEFINING MACRO ATTRIBUTES
-------------------------
-Custom attribute macros can be defined only in the `.gitattributes` file
-at the toplevel (i.e. not in any subdirectory). The built-in attribute
-macro "binary" is equivalent to:
+Custom macro attributes can be defined only in the `.gitattributes`
+file at the toplevel (i.e. not in any subdirectory). The built-in
+macro attribute "binary" is equivalent to:
------------
[attr]binary -diff -text
----------------------------------------------------------------
+SEE ALSO
+--------
+linkgit:git-check-attr[1].
GIT
---