summaryrefslogtreecommitdiff
path: root/Documentation/gitattributes.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/gitattributes.txt')
-rw-r--r--Documentation/gitattributes.txt81
1 files changed, 60 insertions, 21 deletions
diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 412c55b549..2698f63cf9 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -56,6 +56,7 @@ When more than one pattern matches the path, a later line
overrides an earlier line. This overriding is done per
attribute. The rules how the pattern matches paths are the
same as in `.gitignore` files; see linkgit:gitignore[5].
+Unlike `.gitignore`, negative patterns are forbidden.
When deciding what attributes are assigned to a path, git
consults `$GIT_DIR/info/attributes` file (which has the highest
@@ -66,6 +67,11 @@ is from the path in question, the lower its precedence). Finally
global and system-wide files are considered (they have the lowest
precedence).
+When the `.gitattributes` file is missing from the work tree, the
+path in the index is used as a fall-back. During checkout process,
+`.gitattributes` in the index is used and then the file in the
+working tree is used as a fall-back.
+
If you wish to affect only a single repository (i.e., to assign
attributes to files that are particular to
one user's workflow for that repository), then
@@ -75,11 +81,13 @@ repositories (i.e., attributes of interest to all users) should go into
`.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]).
+Its default value is $XDG_CONFIG_HOME/git/attributes. If $XDG_CONFIG_HOME
+is either not set or empty, $HOME/.config/git/attributes is used instead.
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 `!`.
@@ -294,16 +302,27 @@ output is used to update the worktree file. Similarly, the
`clean` command is used to convert the contents of worktree file
upon checkin.
-A missing filter driver definition in the config is not an error
-but makes the filter a no-op passthru.
+One use of the content filtering is to massage the content into a shape
+that is more convenient for the platform, filesystem, and the user to use.
+For this mode of operation, the key phrase here is "more convenient" and
+not "turning something unusable into usable". In other words, the intent
+is that if someone unsets the filter driver definition, or does not have
+the appropriate filter program, the project should still be usable.
+
+Another use of the content filtering is to store the content that cannot
+be directly used in the repository (e.g. a UUID that refers to the true
+content stored outside git, or an encrypted content) and turn it into a
+usable form upon checkout (e.g. download the external content, or decrypt
+the encrypted content).
+
+These two filters behave differently, and by default, a filter is taken as
+the former, massaging the contents into more convenient shape. A missing
+filter driver definition in the config, or a filter driver that exits with
+a non-zero status, is not an error but makes the filter a no-op passthru.
-The content filtering is done to massage the content into a
-shape that is more convenient for the platform, filesystem, and
-the user to use. The key phrase here is "more convenient" and not
-"turning something unusable into usable". In other words, the
-intent is that if someone unsets the filter driver definition,
-or does not have the appropriate filter program, the project
-should still be usable.
+You can declare that a filter turns a content that by itself is unusable
+into a usable content by setting the filter.<driver>.required configuration
+variable to `true`.
For example, in .gitattributes, you would assign the `filter`
attribute for paths.
@@ -335,6 +354,16 @@ input that is already correctly indented. In this case, the lack of a
smudge filter means that the clean filter _must_ accept its own output
without modifying it.
+If a filter _must_ succeed in order to make the stored contents usable,
+you can declare that the filter is `required`, in the configuration:
+
+------------------------
+[filter "crypt"]
+ clean = openssl enc ...
+ smudge = openssl enc -d ...
+ required
+------------------------
+
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:
@@ -488,6 +517,8 @@ configuration file (you still need to enable this with the
attribute mechanism, via `.gitattributes`). The following built in
patterns are available:
+- `ada` suitable for source code in the Ada language.
+
- `bibtex` suitable for files with BibTeX coded references.
- `cpp` suitable for source code in the C and C++ languages.
@@ -500,6 +531,8 @@ patterns are available:
- `java` suitable for source code in the Java language.
+- `matlab` suitable for source code in the MATLAB language.
+
- `objc` suitable for source code in the Objective-C language.
- `pascal` suitable for source code in the Pascal/Delphi language.
@@ -868,7 +901,7 @@ If this attribute is not set or has an invalid value, the value of the
(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
@@ -879,27 +912,30 @@ produced for, any binary file you track. You would need to specify e.g.
------------
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
+[attr]binary -diff -merge -text
------------
@@ -952,6 +988,9 @@ frotz unspecified
----------------------------------------------------------------
+SEE ALSO
+--------
+linkgit:git-check-attr[1].
GIT
---