Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 1 | gitattributes(5) |
| 2 | ================ |
| 3 | |
| 4 | NAME |
| 5 | ---- |
Nguyễn Thái Ngọc Duy | 1b81d8c | 2018-05-20 20:40:02 +0200 | [diff] [blame] | 6 | gitattributes - Defining attributes per path |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
Gustaf Hendeby | e5b5c1d | 2008-08-31 18:00:27 +0200 | [diff] [blame] | 10 | $GIT_DIR/info/attributes, .gitattributes |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 11 | |
| 12 | |
| 13 | DESCRIPTION |
| 14 | ----------- |
| 15 | |
| 16 | A `gitattributes` file is a simple text file that gives |
| 17 | `attributes` to pathnames. |
| 18 | |
| 19 | Each line in `gitattributes` file is of form: |
| 20 | |
Martin Ågren | 8d75a1d | 2019-03-06 07:30:18 +0100 | [diff] [blame] | 21 | pattern attr1 attr2 ... |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 22 | |
Johannes Sixt | 3f74c8e | 2009-02-25 08:54:42 +0100 | [diff] [blame] | 23 | That is, a pattern followed by an attributes list, |
Nguyễn Thái Ngọc Duy | 860a74d | 2017-01-27 18:01:50 -0800 | [diff] [blame] | 24 | separated by whitespaces. Leading and trailing whitespaces are |
| 25 | ignored. Lines that begin with '#' are ignored. Patterns |
| 26 | that begin with a double quote are quoted in C style. |
| 27 | When the pattern matches the path in question, the attributes |
| 28 | listed on the line are given to the path. |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 29 | |
| 30 | Each attribute can be in one of these states for a given path: |
| 31 | |
| 32 | Set:: |
| 33 | |
| 34 | The path has the attribute with special value "true"; |
| 35 | this is specified by listing only the name of the |
| 36 | attribute in the attribute list. |
| 37 | |
| 38 | Unset:: |
| 39 | |
| 40 | The path has the attribute with special value "false"; |
| 41 | this is specified by listing the name of the attribute |
| 42 | prefixed with a dash `-` in the attribute list. |
| 43 | |
| 44 | Set to a value:: |
| 45 | |
| 46 | The path has the attribute with specified string value; |
| 47 | this is specified by listing the name of the attribute |
| 48 | followed by an equal sign `=` and its value in the |
| 49 | attribute list. |
| 50 | |
| 51 | Unspecified:: |
| 52 | |
Johannes Sixt | 3f74c8e | 2009-02-25 08:54:42 +0100 | [diff] [blame] | 53 | No pattern matches the path, and nothing says if |
Junio C Hamano | b9d14ff | 2007-04-24 13:46:02 -0700 | [diff] [blame] | 54 | the path has or does not have the attribute, the |
| 55 | attribute for the path is said to be Unspecified. |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 56 | |
Johannes Sixt | 3f74c8e | 2009-02-25 08:54:42 +0100 | [diff] [blame] | 57 | When more than one pattern matches the path, a later line |
Junio C Hamano | b9d14ff | 2007-04-24 13:46:02 -0700 | [diff] [blame] | 58 | overrides an earlier line. This overriding is done per |
Jeff King | b635ed9 | 2018-03-20 00:14:54 -0400 | [diff] [blame] | 59 | attribute. |
| 60 | |
| 61 | The rules by which the pattern matches paths are the same as in |
| 62 | `.gitignore` files (see linkgit:gitignore[5]), with a few exceptions: |
| 63 | |
| 64 | - negative patterns are forbidden |
| 65 | |
| 66 | - patterns that match a directory do not recursively match paths |
| 67 | inside that directory (so using the trailing-slash `path/` syntax is |
| 68 | pointless in an attributes file; use `path/**` instead) |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 69 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 70 | When deciding what attributes are assigned to a path, Git |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 71 | consults `$GIT_DIR/info/attributes` file (which has the highest |
| 72 | precedence), `.gitattributes` file in the same directory as the |
Jason Merrill | 20ff3ec | 2009-04-06 11:03:36 -0400 | [diff] [blame] | 73 | path in question, and its parent directories up to the toplevel of the |
| 74 | work tree (the further the directory that contains `.gitattributes` |
Petr Onderka | 6df42ab | 2010-09-01 00:42:43 +0200 | [diff] [blame] | 75 | is from the path in question, the lower its precedence). Finally |
| 76 | global and system-wide files are considered (they have the lowest |
| 77 | precedence). |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 78 | |
Nguyen Thai Ngoc Duy | 40701ad | 2012-10-10 20:55:52 +0700 | [diff] [blame] | 79 | When the `.gitattributes` file is missing from the work tree, the |
| 80 | path in the index is used as a fall-back. During checkout process, |
| 81 | `.gitattributes` in the index is used and then the file in the |
| 82 | working tree is used as a fall-back. |
| 83 | |
Jeff King | 90b2290 | 2008-03-27 01:31:00 -0400 | [diff] [blame] | 84 | If you wish to affect only a single repository (i.e., to assign |
Petr Onderka | 6df42ab | 2010-09-01 00:42:43 +0200 | [diff] [blame] | 85 | attributes to files that are particular to |
| 86 | one user's workflow for that repository), then |
Jeff King | 90b2290 | 2008-03-27 01:31:00 -0400 | [diff] [blame] | 87 | attributes should be placed in the `$GIT_DIR/info/attributes` file. |
| 88 | Attributes which should be version-controlled and distributed to other |
| 89 | repositories (i.e., attributes of interest to all users) should go into |
Petr Onderka | 6df42ab | 2010-09-01 00:42:43 +0200 | [diff] [blame] | 90 | `.gitattributes` files. Attributes that should affect all repositories |
| 91 | for a single user should be placed in a file specified by the |
Nguyễn Thái Ngọc Duy | da0005b | 2015-03-11 16:32:45 -0400 | [diff] [blame] | 92 | `core.attributesFile` configuration option (see linkgit:git-config[1]). |
Huynh Khoi Nguyen Nguyen | 684e40f | 2012-06-22 11:03:25 +0200 | [diff] [blame] | 93 | Its default value is $XDG_CONFIG_HOME/git/attributes. If $XDG_CONFIG_HOME |
| 94 | is either not set or empty, $HOME/.config/git/attributes is used instead. |
Petr Onderka | 6df42ab | 2010-09-01 00:42:43 +0200 | [diff] [blame] | 95 | Attributes for all users on a system should be placed in the |
| 96 | `$(prefix)/etc/gitattributes` file. |
Jeff King | 90b2290 | 2008-03-27 01:31:00 -0400 | [diff] [blame] | 97 | |
Stefan Beller | faa4e8c | 2017-01-27 18:01:52 -0800 | [diff] [blame] | 98 | Sometimes you would need to override a setting of an attribute |
Michael Haggerty | 0922570 | 2011-08-03 15:41:30 +0200 | [diff] [blame] | 99 | for a path to `Unspecified` state. This can be done by listing |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 100 | the name of the attribute prefixed with an exclamation point `!`. |
| 101 | |
| 102 | |
Joanna Wang | 2232a88 | 2023-11-16 05:44:37 +0000 | [diff] [blame] | 103 | RESERVED BUILTIN_* ATTRIBUTES |
| 104 | ----------------------------- |
| 105 | |
| 106 | builtin_* is a reserved namespace for builtin attribute values. Any |
| 107 | user defined attributes under this namespace will be ignored and |
| 108 | trigger a warning. |
| 109 | |
| 110 | `builtin_objectmode` |
| 111 | ~~~~~~~~~~~~~~~~~~~~ |
| 112 | This attribute is for filtering files by their file bit modes (40000, |
| 113 | 120000, 160000, 100755, 100644). e.g. ':(attr:builtin_objectmode=160000)'. |
| 114 | You may also check these values with `git check-attr builtin_objectmode -- <file>`. |
| 115 | If the object is not in the index `git check-attr --cached` will return unspecified. |
| 116 | |
| 117 | |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 118 | EFFECTS |
| 119 | ------- |
| 120 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 121 | Certain operations by Git can be influenced by assigning |
Junio C Hamano | ae7aa49 | 2007-07-08 17:15:09 -0700 | [diff] [blame] | 122 | particular attributes to a path. Currently, the following |
| 123 | operations are attributes-aware. |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 124 | |
| 125 | Checking-out and checking-in |
| 126 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 127 | |
Junio C Hamano | 3fed15f | 2007-04-21 19:09:02 -0700 | [diff] [blame] | 128 | These attributes affect how the contents stored in the |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 129 | repository are copied to the working tree files when commands |
Nguyễn Thái Ngọc Duy | d787d31 | 2019-03-29 17:39:05 +0700 | [diff] [blame] | 130 | such as 'git switch', 'git checkout' and 'git merge' run. |
| 131 | They also affect how |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 132 | Git stores the contents you prepare in the working tree in the |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 133 | repository upon 'git add' and 'git commit'. |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 134 | |
Eyvind Bernhardsen | 5ec3e67 | 2010-05-19 22:43:11 +0200 | [diff] [blame] | 135 | `text` |
Junio C Hamano | 3fed15f | 2007-04-21 19:09:02 -0700 | [diff] [blame] | 136 | ^^^^^^ |
| 137 | |
Alex Henrie | 6696077 | 2023-05-02 22:46:56 -0600 | [diff] [blame] | 138 | This attribute marks the path as a text file, which enables end-of-line |
| 139 | conversion: When a matching file is added to the index, the file's line |
| 140 | endings are normalized to LF in the index. Conversely, when the file is |
| 141 | copied from the index to the working directory, its line endings may be |
| 142 | converted from LF to CRLF depending on the `eol` attribute, the Git |
| 143 | config, and the platform (see explanation of `eol` below). |
Junio C Hamano | 3fed15f | 2007-04-21 19:09:02 -0700 | [diff] [blame] | 144 | |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 145 | Set:: |
| 146 | |
Eyvind Bernhardsen | 5ec3e67 | 2010-05-19 22:43:11 +0200 | [diff] [blame] | 147 | Setting the `text` attribute on a path enables end-of-line |
Alex Henrie | 6696077 | 2023-05-02 22:46:56 -0600 | [diff] [blame] | 148 | conversion on checkin and checkout as described above. Line endings |
| 149 | are normalized to LF in the index every time the file is checked in, |
| 150 | even if the file was previously added to Git with CRLF line endings. |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 151 | |
| 152 | Unset:: |
| 153 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 154 | Unsetting the `text` attribute on a path tells Git not to |
Junio C Hamano | bbb896d | 2008-08-30 14:35:15 -0700 | [diff] [blame] | 155 | attempt any end-of-line conversion upon checkin or checkout. |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 156 | |
Eyvind Bernhardsen | fd6cce9 | 2010-05-19 22:43:10 +0200 | [diff] [blame] | 157 | Set to string value "auto":: |
| 158 | |
Alex Henrie | 6696077 | 2023-05-02 22:46:56 -0600 | [diff] [blame] | 159 | When `text` is set to "auto", Git decides by itself whether the file |
| 160 | is text or binary. If it is text and the file was not already in |
| 161 | Git with CRLF endings, line endings are converted on checkin and |
| 162 | checkout as described above. Otherwise, no conversion is done on |
| 163 | checkin or checkout. |
Eyvind Bernhardsen | fd6cce9 | 2010-05-19 22:43:10 +0200 | [diff] [blame] | 164 | |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 165 | Unspecified:: |
| 166 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 167 | If the `text` attribute is unspecified, Git uses the |
Eyvind Bernhardsen | 942e774 | 2010-06-04 21:29:08 +0200 | [diff] [blame] | 168 | `core.autocrlf` configuration variable to determine if the |
| 169 | file should be converted. |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 170 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 171 | Any other value causes Git to act as if `text` has been left |
Eyvind Bernhardsen | fd6cce9 | 2010-05-19 22:43:10 +0200 | [diff] [blame] | 172 | unspecified. |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 173 | |
Eyvind Bernhardsen | fd6cce9 | 2010-05-19 22:43:10 +0200 | [diff] [blame] | 174 | `eol` |
| 175 | ^^^^^ |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 176 | |
Alex Henrie | 6696077 | 2023-05-02 22:46:56 -0600 | [diff] [blame] | 177 | This attribute marks a path to use a specific line-ending style in the |
| 178 | working tree when it is checked out. It has effect only if `text` or |
| 179 | `text=auto` is set (see above), but specifying `eol` automatically sets |
| 180 | `text` if `text` was left unspecified. |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 181 | |
Eyvind Bernhardsen | fd6cce9 | 2010-05-19 22:43:10 +0200 | [diff] [blame] | 182 | Set to string value "crlf":: |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 183 | |
Alex Henrie | 6696077 | 2023-05-02 22:46:56 -0600 | [diff] [blame] | 184 | This setting converts the file's line endings in the working |
| 185 | directory to CRLF when the file is checked out. |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 186 | |
Eyvind Bernhardsen | fd6cce9 | 2010-05-19 22:43:10 +0200 | [diff] [blame] | 187 | Set to string value "lf":: |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 188 | |
Alex Henrie | 6696077 | 2023-05-02 22:46:56 -0600 | [diff] [blame] | 189 | This setting uses the same line endings in the working directory as |
| 190 | in the index when the file is checked out. |
| 191 | |
| 192 | Unspecified:: |
| 193 | |
| 194 | If the `eol` attribute is unspecified for a file, its line endings |
| 195 | in the working directory are determined by the `core.autocrlf` or |
| 196 | `core.eol` configuration variable (see the definitions of those |
| 197 | options in linkgit:git-config[1]). If `text` is set but neither of |
| 198 | those variables is, the default is `eol=crlf` on Windows and |
| 199 | `eol=lf` on all other platforms. |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 200 | |
Eyvind Bernhardsen | 5ec3e67 | 2010-05-19 22:43:11 +0200 | [diff] [blame] | 201 | Backwards compatibility with `crlf` attribute |
| 202 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 203 | |
| 204 | For backwards compatibility, the `crlf` attribute is interpreted as |
| 205 | follows: |
| 206 | |
| 207 | ------------------------ |
| 208 | crlf text |
| 209 | -crlf -text |
| 210 | crlf=input eol=lf |
| 211 | ------------------------ |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 212 | |
Eyvind Bernhardsen | fd6cce9 | 2010-05-19 22:43:10 +0200 | [diff] [blame] | 213 | End-of-line conversion |
| 214 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 215 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 216 | While Git normally leaves file contents alone, it can be configured to |
Eyvind Bernhardsen | fd6cce9 | 2010-05-19 22:43:10 +0200 | [diff] [blame] | 217 | normalize line endings to LF in the repository and, optionally, to |
| 218 | convert them to CRLF when files are checked out. |
| 219 | |
Torsten Bögershausen | e28eae3 | 2016-08-26 22:18:48 +0200 | [diff] [blame] | 220 | If you simply want to have CRLF line endings in your working directory |
| 221 | regardless of the repository you are working with, you can set the |
| 222 | config variable "core.autocrlf" without using any attributes. |
| 223 | |
| 224 | ------------------------ |
| 225 | [core] |
| 226 | autocrlf = true |
| 227 | ------------------------ |
| 228 | |
| 229 | This does not force normalization of text files, but does ensure |
| 230 | that text files that you introduce to the repository have their line |
| 231 | endings normalized to LF when they are added, and that files that are |
| 232 | already normalized in the repository stay normalized. |
| 233 | |
| 234 | If you want to ensure that text files that any contributor introduces to |
| 235 | the repository have their line endings normalized, you can set the |
| 236 | `text` attribute to "auto" for _all_ files. |
| 237 | |
| 238 | ------------------------ |
| 239 | * text=auto |
| 240 | ------------------------ |
| 241 | |
| 242 | The attributes allow a fine-grained control, how the line endings |
| 243 | are converted. |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 244 | Here is an example that will make Git normalize .txt, .vcproj and .sh |
Eyvind Bernhardsen | fd6cce9 | 2010-05-19 22:43:10 +0200 | [diff] [blame] | 245 | files, ensure that .vcproj files have CRLF and .sh files have LF in |
| 246 | the working directory, and prevent .jpg files from being normalized |
| 247 | regardless of their content. |
| 248 | |
| 249 | ------------------------ |
Torsten Bögershausen | 6523728 | 2016-06-28 10:01:13 +0200 | [diff] [blame] | 250 | * text=auto |
Eyvind Bernhardsen | 5ec3e67 | 2010-05-19 22:43:11 +0200 | [diff] [blame] | 251 | *.txt text |
Torsten Bögershausen | 6523728 | 2016-06-28 10:01:13 +0200 | [diff] [blame] | 252 | *.vcproj text eol=crlf |
| 253 | *.sh text eol=lf |
Eyvind Bernhardsen | 5ec3e67 | 2010-05-19 22:43:11 +0200 | [diff] [blame] | 254 | *.jpg -text |
Eyvind Bernhardsen | fd6cce9 | 2010-05-19 22:43:10 +0200 | [diff] [blame] | 255 | ------------------------ |
| 256 | |
Torsten Bögershausen | e28eae3 | 2016-08-26 22:18:48 +0200 | [diff] [blame] | 257 | NOTE: When `text=auto` conversion is enabled in a cross-platform |
| 258 | project using push and pull to a central repository the text files |
| 259 | containing CRLFs should be normalized. |
Eyvind Bernhardsen | fd6cce9 | 2010-05-19 22:43:10 +0200 | [diff] [blame] | 260 | |
Torsten Bögershausen | e28eae3 | 2016-08-26 22:18:48 +0200 | [diff] [blame] | 261 | From a clean working directory: |
Eyvind Bernhardsen | fd6cce9 | 2010-05-19 22:43:10 +0200 | [diff] [blame] | 262 | |
| 263 | ------------------------------------------------- |
Torsten Bögershausen | e28eae3 | 2016-08-26 22:18:48 +0200 | [diff] [blame] | 264 | $ echo "* text=auto" >.gitattributes |
Torsten Bögershausen | 9472935 | 2017-11-16 17:38:28 +0100 | [diff] [blame] | 265 | $ git add --renormalize . |
Eyvind Bernhardsen | fd6cce9 | 2010-05-19 22:43:10 +0200 | [diff] [blame] | 266 | $ git status # Show files that will be normalized |
Eyvind Bernhardsen | fd6cce9 | 2010-05-19 22:43:10 +0200 | [diff] [blame] | 267 | $ git commit -m "Introduce end-of-line normalization" |
| 268 | ------------------------------------------------- |
| 269 | |
| 270 | If any files that should not be normalized show up in 'git status', |
Eyvind Bernhardsen | 5ec3e67 | 2010-05-19 22:43:11 +0200 | [diff] [blame] | 271 | unset their `text` attribute before running 'git add -u'. |
Eyvind Bernhardsen | fd6cce9 | 2010-05-19 22:43:10 +0200 | [diff] [blame] | 272 | |
| 273 | ------------------------ |
Eyvind Bernhardsen | 5ec3e67 | 2010-05-19 22:43:11 +0200 | [diff] [blame] | 274 | manual.pdf -text |
Eyvind Bernhardsen | fd6cce9 | 2010-05-19 22:43:10 +0200 | [diff] [blame] | 275 | ------------------------ |
| 276 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 277 | Conversely, text files that Git does not detect can have normalization |
Eyvind Bernhardsen | fd6cce9 | 2010-05-19 22:43:10 +0200 | [diff] [blame] | 278 | enabled manually. |
| 279 | |
| 280 | ------------------------ |
Eyvind Bernhardsen | 5ec3e67 | 2010-05-19 22:43:11 +0200 | [diff] [blame] | 281 | weirdchars.txt text |
Eyvind Bernhardsen | fd6cce9 | 2010-05-19 22:43:10 +0200 | [diff] [blame] | 282 | ------------------------ |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 283 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 284 | If `core.safecrlf` is set to "true" or "warn", Git verifies if |
Steffen Prohaska | 21e5ad5 | 2008-02-06 12:25:58 +0100 | [diff] [blame] | 285 | the conversion is reversible for the current setting of |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 286 | `core.autocrlf`. For "true", Git rejects irreversible |
| 287 | conversions; for "warn", Git only prints a warning but accepts |
Steffen Prohaska | 21e5ad5 | 2008-02-06 12:25:58 +0100 | [diff] [blame] | 288 | an irreversible conversion. The safety triggers to prevent such |
| 289 | a conversion done to the files in the work tree, but there are a |
| 290 | few exceptions. Even though... |
| 291 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 292 | - 'git add' itself does not touch the files in the work tree, the |
Steffen Prohaska | 21e5ad5 | 2008-02-06 12:25:58 +0100 | [diff] [blame] | 293 | next checkout would, so the safety triggers; |
| 294 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 295 | - 'git apply' to update a text file with a patch does touch the files |
Steffen Prohaska | 21e5ad5 | 2008-02-06 12:25:58 +0100 | [diff] [blame] | 296 | in the work tree, but the operation is about text files and CRLF |
| 297 | conversion is about fixing the line ending inconsistencies, so the |
| 298 | safety does not trigger; |
| 299 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 300 | - 'git diff' itself does not touch the files in the work tree, it is |
| 301 | often run to inspect the changes you intend to next 'git add'. To |
Steffen Prohaska | 21e5ad5 | 2008-02-06 12:25:58 +0100 | [diff] [blame] | 302 | catch potential problems early, safety triggers. |
| 303 | |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 304 | |
Lars Schneider | 107642f | 2018-04-15 20:16:07 +0200 | [diff] [blame] | 305 | `working-tree-encoding` |
| 306 | ^^^^^^^^^^^^^^^^^^^^^^^ |
| 307 | |
| 308 | Git recognizes files encoded in ASCII or one of its supersets (e.g. |
| 309 | UTF-8, ISO-8859-1, ...) as text files. Files encoded in certain other |
| 310 | encodings (e.g. UTF-16) are interpreted as binary and consequently |
| 311 | built-in Git text processing tools (e.g. 'git diff') as well as most Git |
| 312 | web front ends do not visualize the contents of these files by default. |
| 313 | |
| 314 | In these cases you can tell Git the encoding of a file in the working |
| 315 | directory with the `working-tree-encoding` attribute. If a file with this |
Elijah Newren | 031fd4b | 2019-11-05 17:07:20 +0000 | [diff] [blame] | 316 | attribute is added to Git, then Git re-encodes the content from the |
Lars Schneider | 107642f | 2018-04-15 20:16:07 +0200 | [diff] [blame] | 317 | specified encoding to UTF-8. Finally, Git stores the UTF-8 encoded |
| 318 | content in its internal data structure (called "the index"). On checkout |
Elijah Newren | 031fd4b | 2019-11-05 17:07:20 +0000 | [diff] [blame] | 319 | the content is re-encoded back to the specified encoding. |
Lars Schneider | 107642f | 2018-04-15 20:16:07 +0200 | [diff] [blame] | 320 | |
| 321 | Please note that using the `working-tree-encoding` attribute may have a |
| 322 | number of pitfalls: |
| 323 | |
| 324 | - Alternative Git implementations (e.g. JGit or libgit2) and older Git |
| 325 | versions (as of March 2018) do not support the `working-tree-encoding` |
| 326 | attribute. If you decide to use the `working-tree-encoding` attribute |
| 327 | in your repository, then it is strongly recommended to ensure that all |
| 328 | clients working with the repository support it. |
Andreas Heiduk | ad47194 | 2018-10-22 22:45:43 +0200 | [diff] [blame] | 329 | + |
| 330 | For example, Microsoft Visual Studio resources files (`*.rc`) or |
| 331 | PowerShell script files (`*.ps1`) are sometimes encoded in UTF-16. |
| 332 | If you declare `*.ps1` as files as UTF-16 and you add `foo.ps1` with |
| 333 | a `working-tree-encoding` enabled Git client, then `foo.ps1` will be |
| 334 | stored as UTF-8 internally. A client without `working-tree-encoding` |
| 335 | support will checkout `foo.ps1` as UTF-8 encoded file. This will |
| 336 | typically cause trouble for the users of this file. |
| 337 | + |
Alexander Blesius | ed31851 | 2019-03-16 11:34:39 +0100 | [diff] [blame] | 338 | If a Git client that does not support the `working-tree-encoding` |
| 339 | attribute adds a new file `bar.ps1`, then `bar.ps1` will be |
Andreas Heiduk | ad47194 | 2018-10-22 22:45:43 +0200 | [diff] [blame] | 340 | stored "as-is" internally (in this example probably as UTF-16). |
| 341 | A client with `working-tree-encoding` support will interpret the |
| 342 | internal contents as UTF-8 and try to convert it to UTF-16 on checkout. |
| 343 | That operation will fail and cause an error. |
Lars Schneider | 107642f | 2018-04-15 20:16:07 +0200 | [diff] [blame] | 344 | |
Lars Schneider | e92d622 | 2018-04-15 20:16:10 +0200 | [diff] [blame] | 345 | - Reencoding content to non-UTF encodings can cause errors as the |
| 346 | conversion might not be UTF-8 round trip safe. If you suspect your |
| 347 | encoding to not be round trip safe, then add it to |
| 348 | `core.checkRoundtripEncoding` to make Git check the round trip |
| 349 | encoding (see linkgit:git-config[1]). SHIFT-JIS (Japanese character |
| 350 | set) is known to have round trip issues with UTF-8 and is checked by |
| 351 | default. |
| 352 | |
Lars Schneider | 107642f | 2018-04-15 20:16:07 +0200 | [diff] [blame] | 353 | - Reencoding content requires resources that might slow down certain |
| 354 | Git operations (e.g 'git checkout' or 'git add'). |
| 355 | |
| 356 | Use the `working-tree-encoding` attribute only if you cannot store a file |
| 357 | in UTF-8 encoding and if you want Git to be able to process the content |
| 358 | as text. |
| 359 | |
| 360 | As an example, use the following attributes if your '*.ps1' files are |
| 361 | UTF-16 encoded with byte order mark (BOM) and you want Git to perform |
| 362 | automatic line ending conversion based on your platform. |
| 363 | |
| 364 | ------------------------ |
| 365 | *.ps1 text working-tree-encoding=UTF-16 |
| 366 | ------------------------ |
| 367 | |
| 368 | Use the following attributes if your '*.ps1' files are UTF-16 little |
| 369 | endian encoded without BOM and you want Git to use Windows line endings |
Yash Bhatambare | e6e1519 | 2019-03-06 05:23:10 +0000 | [diff] [blame] | 370 | in the working directory (use `UTF-16LE-BOM` instead of `UTF-16LE` if |
Torsten Bögershausen | aab2a1a | 2019-01-30 16:01:52 +0100 | [diff] [blame] | 371 | you want UTF-16 little endian with BOM). |
| 372 | Please note, it is highly recommended to |
Lars Schneider | 107642f | 2018-04-15 20:16:07 +0200 | [diff] [blame] | 373 | explicitly define the line endings with `eol` if the `working-tree-encoding` |
| 374 | attribute is used to avoid ambiguity. |
| 375 | |
| 376 | ------------------------ |
| 377 | *.ps1 text working-tree-encoding=UTF-16LE eol=CRLF |
| 378 | ------------------------ |
| 379 | |
| 380 | You can get a list of all available encodings on your platform with the |
| 381 | following command: |
| 382 | |
| 383 | ------------------------ |
| 384 | iconv --list |
| 385 | ------------------------ |
| 386 | |
| 387 | If you do not know the encoding of a file, then you can use the `file` |
| 388 | command to guess the encoding: |
| 389 | |
| 390 | ------------------------ |
| 391 | file foo.ps1 |
| 392 | ------------------------ |
| 393 | |
| 394 | |
Junio C Hamano | 3fed15f | 2007-04-21 19:09:02 -0700 | [diff] [blame] | 395 | `ident` |
| 396 | ^^^^^^^ |
| 397 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 398 | When the attribute `ident` is set for a path, Git replaces |
Jan Krüger | 2c850f1 | 2008-10-30 19:14:33 +0100 | [diff] [blame] | 399 | `$Id$` in the blob object with `$Id:`, followed by the |
Junio C Hamano | 3fed15f | 2007-04-21 19:09:02 -0700 | [diff] [blame] | 400 | 40-character hexadecimal blob object name, followed by a dollar |
| 401 | sign `$` upon checkout. Any byte sequence that begins with |
Andy Parkins | af9b54b | 2007-05-14 14:37:25 +0100 | [diff] [blame] | 402 | `$Id:` and ends with `$` in the worktree file is replaced |
| 403 | with `$Id$` upon check-in. |
Junio C Hamano | 3fed15f | 2007-04-21 19:09:02 -0700 | [diff] [blame] | 404 | |
| 405 | |
Junio C Hamano | aa4ed40 | 2007-04-21 03:14:13 -0700 | [diff] [blame] | 406 | `filter` |
| 407 | ^^^^^^^^ |
| 408 | |
Wincent Colaiuta | c05ef93 | 2007-11-14 08:51:41 +0100 | [diff] [blame] | 409 | A `filter` attribute can be set to a string value that names a |
Junio C Hamano | aa4ed40 | 2007-04-21 03:14:13 -0700 | [diff] [blame] | 410 | filter driver specified in the configuration. |
| 411 | |
Wincent Colaiuta | c05ef93 | 2007-11-14 08:51:41 +0100 | [diff] [blame] | 412 | A filter driver consists of a `clean` command and a `smudge` |
Junio C Hamano | aa4ed40 | 2007-04-21 03:14:13 -0700 | [diff] [blame] | 413 | command, either of which can be left unspecified. Upon |
Wincent Colaiuta | c05ef93 | 2007-11-14 08:51:41 +0100 | [diff] [blame] | 414 | checkout, when the `smudge` command is specified, the command is |
| 415 | fed the blob object from its standard input, and its standard |
| 416 | output is used to update the worktree file. Similarly, the |
| 417 | `clean` command is used to convert the contents of worktree file |
Lars Schneider | edcc858 | 2016-10-16 16:20:37 -0700 | [diff] [blame] | 418 | upon checkin. By default these commands process only a single |
| 419 | blob and terminate. If a long running `process` filter is used |
| 420 | in place of `clean` and/or `smudge` filters, then Git can process |
| 421 | all blobs with a single filter command invocation for the entire |
| 422 | life of a single Git command, for example `git add --all`. If a |
| 423 | long running `process` filter is configured then it always takes |
| 424 | precedence over a configured single blob filter. See section |
| 425 | below for the description of the protocol used to communicate with |
| 426 | a `process` filter. |
Junio C Hamano | aa4ed40 | 2007-04-21 03:14:13 -0700 | [diff] [blame] | 427 | |
Jehan Bing | 36daaac | 2012-02-16 17:19:03 -0800 | [diff] [blame] | 428 | One use of the content filtering is to massage the content into a shape |
| 429 | that is more convenient for the platform, filesystem, and the user to use. |
| 430 | For this mode of operation, the key phrase here is "more convenient" and |
| 431 | not "turning something unusable into usable". In other words, the intent |
| 432 | is that if someone unsets the filter driver definition, or does not have |
| 433 | the appropriate filter program, the project should still be usable. |
Junio C Hamano | aa4ed40 | 2007-04-21 03:14:13 -0700 | [diff] [blame] | 434 | |
Jehan Bing | 36daaac | 2012-02-16 17:19:03 -0800 | [diff] [blame] | 435 | Another use of the content filtering is to store the content that cannot |
| 436 | be directly used in the repository (e.g. a UUID that refers to the true |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 437 | content stored outside Git, or an encrypted content) and turn it into a |
Jehan Bing | 36daaac | 2012-02-16 17:19:03 -0800 | [diff] [blame] | 438 | usable form upon checkout (e.g. download the external content, or decrypt |
| 439 | the encrypted content). |
| 440 | |
| 441 | These two filters behave differently, and by default, a filter is taken as |
| 442 | the former, massaging the contents into more convenient shape. A missing |
| 443 | filter driver definition in the config, or a filter driver that exits with |
| 444 | a non-zero status, is not an error but makes the filter a no-op passthru. |
| 445 | |
| 446 | You can declare that a filter turns a content that by itself is unusable |
| 447 | into a usable content by setting the filter.<driver>.required configuration |
| 448 | variable to `true`. |
Junio C Hamano | aa4ed40 | 2007-04-21 03:14:13 -0700 | [diff] [blame] | 449 | |
Torsten Bögershausen | 9472935 | 2017-11-16 17:38:28 +0100 | [diff] [blame] | 450 | Note: Whenever the clean filter is changed, the repo should be renormalized: |
| 451 | $ git add --renormalize . |
| 452 | |
Nanako Shiraishi | d79f5d1 | 2009-12-15 12:11:10 +0900 | [diff] [blame] | 453 | For example, in .gitattributes, you would assign the `filter` |
| 454 | attribute for paths. |
| 455 | |
| 456 | ------------------------ |
| 457 | *.c filter=indent |
| 458 | ------------------------ |
| 459 | |
| 460 | Then you would define a "filter.indent.clean" and "filter.indent.smudge" |
| 461 | configuration in your .git/config to specify a pair of commands to |
| 462 | modify the contents of C programs when the source files are checked |
| 463 | in ("clean" is run) and checked out (no change is made because the |
| 464 | command is "cat"). |
| 465 | |
| 466 | ------------------------ |
| 467 | [filter "indent"] |
| 468 | clean = indent |
| 469 | smudge = cat |
| 470 | ------------------------ |
| 471 | |
Eyvind Bernhardsen | f217f0e | 2010-07-02 21:20:47 +0200 | [diff] [blame] | 472 | For best results, `clean` should not alter its output further if it is |
| 473 | run twice ("clean->clean" should be equivalent to "clean"), and |
| 474 | multiple `smudge` commands should not alter `clean`'s output |
| 475 | ("smudge->smudge->clean" should be equivalent to "clean"). See the |
| 476 | section on merging below. |
| 477 | |
| 478 | The "indent" filter is well-behaved in this regard: it will not modify |
| 479 | input that is already correctly indented. In this case, the lack of a |
| 480 | smudge filter means that the clean filter _must_ accept its own output |
| 481 | without modifying it. |
| 482 | |
Jehan Bing | 36daaac | 2012-02-16 17:19:03 -0800 | [diff] [blame] | 483 | If a filter _must_ succeed in order to make the stored contents usable, |
| 484 | you can declare that the filter is `required`, in the configuration: |
| 485 | |
| 486 | ------------------------ |
| 487 | [filter "crypt"] |
| 488 | clean = openssl enc ... |
| 489 | smudge = openssl enc -d ... |
| 490 | required |
| 491 | ------------------------ |
| 492 | |
Pete Wyckoff | a2b665d | 2010-12-22 06:40:13 -0800 | [diff] [blame] | 493 | Sequence "%f" on the filter command line is replaced with the name of |
| 494 | the file the filter is working on. A filter might use this in keyword |
| 495 | substitution. For example: |
| 496 | |
| 497 | ------------------------ |
| 498 | [filter "p4"] |
| 499 | clean = git-p4-filter --clean %f |
| 500 | smudge = git-p4-filter --smudge %f |
| 501 | ------------------------ |
| 502 | |
Joey Hess | 52db4b0 | 2016-07-11 18:45:05 -0400 | [diff] [blame] | 503 | Note that "%f" is the name of the path that is being worked on. Depending |
| 504 | on the version that is being filtered, the corresponding file on disk may |
| 505 | not exist, or may have different contents. So, smudge and clean commands |
| 506 | should not try to access the file on disk, but only act as filters on the |
| 507 | content provided to them on standard input. |
Junio C Hamano | aa4ed40 | 2007-04-21 03:14:13 -0700 | [diff] [blame] | 508 | |
Lars Schneider | edcc858 | 2016-10-16 16:20:37 -0700 | [diff] [blame] | 509 | Long Running Filter Process |
| 510 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 511 | |
| 512 | If the filter command (a string value) is defined via |
| 513 | `filter.<driver>.process` then Git can process all blobs with a |
| 514 | single filter invocation for the entire life of a single Git |
Jonathan Tan | addad10 | 2018-01-25 10:53:24 -0800 | [diff] [blame] | 515 | command. This is achieved by using the long-running process protocol |
| 516 | (described in technical/long-running-process-protocol.txt). |
Lars Schneider | edcc858 | 2016-10-16 16:20:37 -0700 | [diff] [blame] | 517 | |
Jonathan Tan | addad10 | 2018-01-25 10:53:24 -0800 | [diff] [blame] | 518 | When Git encounters the first file that needs to be cleaned or smudged, |
| 519 | it starts the filter and performs the handshake. In the handshake, the |
| 520 | welcome message sent by Git is "git-filter-client", only version 2 is |
Elijah Newren | 031fd4b | 2019-11-05 17:07:20 +0000 | [diff] [blame] | 521 | supported, and the supported capabilities are "clean", "smudge", and |
Jonathan Tan | addad10 | 2018-01-25 10:53:24 -0800 | [diff] [blame] | 522 | "delay". |
Lars Schneider | edcc858 | 2016-10-16 16:20:37 -0700 | [diff] [blame] | 523 | |
| 524 | Afterwards Git sends a list of "key=value" pairs terminated with |
| 525 | a flush packet. The list will contain at least the filter command |
| 526 | (based on the supported capabilities) and the pathname of the file |
| 527 | to filter relative to the repository root. Right after the flush packet |
| 528 | Git sends the content split in zero or more pkt-line packets and a |
| 529 | flush packet to terminate content. Please note, that the filter |
| 530 | must not send any response before it received the content and the |
Lars Schneider | c6b0831 | 2016-12-03 20:45:16 +0100 | [diff] [blame] | 531 | final flush packet. Also note that the "value" of a "key=value" pair |
| 532 | can contain the "=" character whereas the key would never contain |
| 533 | that character. |
Lars Schneider | edcc858 | 2016-10-16 16:20:37 -0700 | [diff] [blame] | 534 | ------------------------ |
| 535 | packet: git> command=smudge |
| 536 | packet: git> pathname=path/testfile.dat |
| 537 | packet: git> 0000 |
| 538 | packet: git> CONTENT |
| 539 | packet: git> 0000 |
| 540 | ------------------------ |
| 541 | |
| 542 | The filter is expected to respond with a list of "key=value" pairs |
| 543 | terminated with a flush packet. If the filter does not experience |
| 544 | problems then the list must contain a "success" status. Right after |
| 545 | these packets the filter is expected to send the content in zero |
| 546 | or more pkt-line packets and a flush packet at the end. Finally, a |
| 547 | second list of "key=value" pairs terminated with a flush packet |
| 548 | is expected. The filter can change the status in the second list |
| 549 | or keep the status as is with an empty list. Please note that the |
| 550 | empty list must be terminated with a flush packet regardless. |
| 551 | |
| 552 | ------------------------ |
| 553 | packet: git< status=success |
| 554 | packet: git< 0000 |
| 555 | packet: git< SMUDGED_CONTENT |
| 556 | packet: git< 0000 |
| 557 | packet: git< 0000 # empty list, keep "status=success" unchanged! |
| 558 | ------------------------ |
| 559 | |
| 560 | If the result content is empty then the filter is expected to respond |
| 561 | with a "success" status and a flush packet to signal the empty content. |
| 562 | ------------------------ |
| 563 | packet: git< status=success |
| 564 | packet: git< 0000 |
| 565 | packet: git< 0000 # empty content! |
| 566 | packet: git< 0000 # empty list, keep "status=success" unchanged! |
| 567 | ------------------------ |
| 568 | |
| 569 | In case the filter cannot or does not want to process the content, |
| 570 | it is expected to respond with an "error" status. |
| 571 | ------------------------ |
| 572 | packet: git< status=error |
| 573 | packet: git< 0000 |
| 574 | ------------------------ |
| 575 | |
| 576 | If the filter experiences an error during processing, then it can |
| 577 | send the status "error" after the content was (partially or |
| 578 | completely) sent. |
| 579 | ------------------------ |
| 580 | packet: git< status=success |
| 581 | packet: git< 0000 |
| 582 | packet: git< HALF_WRITTEN_ERRONEOUS_CONTENT |
| 583 | packet: git< 0000 |
| 584 | packet: git< status=error |
| 585 | packet: git< 0000 |
| 586 | ------------------------ |
| 587 | |
| 588 | In case the filter cannot or does not want to process the content |
| 589 | as well as any future content for the lifetime of the Git process, |
| 590 | then it is expected to respond with an "abort" status at any point |
| 591 | in the protocol. |
| 592 | ------------------------ |
| 593 | packet: git< status=abort |
| 594 | packet: git< 0000 |
| 595 | ------------------------ |
| 596 | |
| 597 | Git neither stops nor restarts the filter process in case the |
| 598 | "error"/"abort" status is set. However, Git sets its exit code |
| 599 | according to the `filter.<driver>.required` flag, mimicking the |
| 600 | behavior of the `filter.<driver>.clean` / `filter.<driver>.smudge` |
| 601 | mechanism. |
| 602 | |
| 603 | If the filter dies during the communication or does not adhere to |
| 604 | the protocol then Git will stop the filter process and restart it |
| 605 | with the next file that needs to be processed. Depending on the |
| 606 | `filter.<driver>.required` flag Git will interpret that as error. |
| 607 | |
Lars Schneider | 2841e8f | 2017-06-30 22:41:28 +0200 | [diff] [blame] | 608 | Delay |
| 609 | ^^^^^ |
| 610 | |
| 611 | If the filter supports the "delay" capability, then Git can send the |
| 612 | flag "can-delay" after the filter command and pathname. This flag |
| 613 | denotes that the filter can delay filtering the current blob (e.g. to |
| 614 | compensate network latencies) by responding with no content but with |
| 615 | the status "delayed" and a flush packet. |
| 616 | ------------------------ |
| 617 | packet: git> command=smudge |
| 618 | packet: git> pathname=path/testfile.dat |
| 619 | packet: git> can-delay=1 |
| 620 | packet: git> 0000 |
| 621 | packet: git> CONTENT |
| 622 | packet: git> 0000 |
| 623 | packet: git< status=delayed |
| 624 | packet: git< 0000 |
| 625 | ------------------------ |
| 626 | |
| 627 | If the filter supports the "delay" capability then it must support the |
| 628 | "list_available_blobs" command. If Git sends this command, then the |
| 629 | filter is expected to return a list of pathnames representing blobs |
| 630 | that have been delayed earlier and are now available. |
| 631 | The list must be terminated with a flush packet followed |
| 632 | by a "success" status that is also terminated with a flush packet. If |
| 633 | no blobs for the delayed paths are available, yet, then the filter is |
| 634 | expected to block the response until at least one blob becomes |
| 635 | available. The filter can tell Git that it has no more delayed blobs |
| 636 | by sending an empty list. As soon as the filter responds with an empty |
| 637 | list, Git stops asking. All blobs that Git has not received at this |
| 638 | point are considered missing and will result in an error. |
| 639 | |
| 640 | ------------------------ |
| 641 | packet: git> command=list_available_blobs |
| 642 | packet: git> 0000 |
| 643 | packet: git< pathname=path/testfile.dat |
| 644 | packet: git< pathname=path/otherfile.dat |
| 645 | packet: git< 0000 |
| 646 | packet: git< status=success |
| 647 | packet: git< 0000 |
| 648 | ------------------------ |
| 649 | |
| 650 | After Git received the pathnames, it will request the corresponding |
| 651 | blobs again. These requests contain a pathname and an empty content |
| 652 | section. The filter is expected to respond with the smudged content |
| 653 | in the usual way as explained above. |
| 654 | ------------------------ |
| 655 | packet: git> command=smudge |
| 656 | packet: git> pathname=path/testfile.dat |
| 657 | packet: git> 0000 |
| 658 | packet: git> 0000 # empty content! |
| 659 | packet: git< status=success |
| 660 | packet: git< 0000 |
| 661 | packet: git< SMUDGED_CONTENT |
| 662 | packet: git< 0000 |
| 663 | packet: git< 0000 # empty list, keep "status=success" unchanged! |
| 664 | ------------------------ |
| 665 | |
| 666 | Example |
| 667 | ^^^^^^^ |
| 668 | |
Lars Schneider | 0f71fa2 | 2016-10-16 16:20:38 -0700 | [diff] [blame] | 669 | A long running filter demo implementation can be found in |
| 670 | `contrib/long-running-filter/example.pl` located in the Git |
| 671 | core repository. If you develop your own long running filter |
Lars Schneider | edcc858 | 2016-10-16 16:20:37 -0700 | [diff] [blame] | 672 | process then the `GIT_TRACE_PACKET` environment variables can be |
| 673 | very helpful for debugging (see linkgit:git[1]). |
| 674 | |
| 675 | Please note that you cannot use an existing `filter.<driver>.clean` |
| 676 | or `filter.<driver>.smudge` command with `filter.<driver>.process` |
| 677 | because the former two use a different inter process communication |
| 678 | protocol than the latter one. |
| 679 | |
| 680 | |
Junio C Hamano | aa4ed40 | 2007-04-21 03:14:13 -0700 | [diff] [blame] | 681 | Interaction between checkin/checkout attributes |
| 682 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 683 | |
| 684 | In the check-in codepath, the worktree file is first converted |
| 685 | with `filter` driver (if specified and corresponding driver |
| 686 | defined), then the result is processed with `ident` (if |
Eyvind Bernhardsen | 5ec3e67 | 2010-05-19 22:43:11 +0200 | [diff] [blame] | 687 | specified), and then finally with `text` (again, if specified |
Junio C Hamano | aa4ed40 | 2007-04-21 03:14:13 -0700 | [diff] [blame] | 688 | and applicable). |
| 689 | |
| 690 | In the check-out codepath, the blob content is first converted |
Eyvind Bernhardsen | 5ec3e67 | 2010-05-19 22:43:11 +0200 | [diff] [blame] | 691 | with `text`, and then `ident` and fed to `filter`. |
Junio C Hamano | aa4ed40 | 2007-04-21 03:14:13 -0700 | [diff] [blame] | 692 | |
| 693 | |
Eyvind Bernhardsen | f217f0e | 2010-07-02 21:20:47 +0200 | [diff] [blame] | 694 | Merging branches with differing checkin/checkout attributes |
| 695 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 696 | |
| 697 | If you have added attributes to a file that cause the canonical |
| 698 | repository format for that file to change, such as adding a |
| 699 | clean/smudge filter or text/eol/ident attributes, merging anything |
| 700 | where the attribute is not in place would normally cause merge |
| 701 | conflicts. |
| 702 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 703 | To prevent these unnecessary merge conflicts, Git can be told to run a |
Eyvind Bernhardsen | f217f0e | 2010-07-02 21:20:47 +0200 | [diff] [blame] | 704 | virtual check-out and check-in of all three stages of a file when |
| 705 | resolving a three-way merge by setting the `merge.renormalize` |
| 706 | configuration variable. This prevents changes caused by check-in |
| 707 | conversion from causing spurious merge conflicts when a converted file |
| 708 | is merged with an unconverted file. |
| 709 | |
| 710 | As long as a "smudge->clean" results in the same output as a "clean" |
| 711 | even on files that are already smudged, this strategy will |
| 712 | automatically resolve all filter-related conflicts. Filters that do |
| 713 | not act in this way may cause additional merge conflicts that must be |
| 714 | resolved manually. |
| 715 | |
| 716 | |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 717 | Generating diff text |
| 718 | ~~~~~~~~~~~~~~~~~~~~ |
| 719 | |
Jakub Narebski | 4f73e24 | 2008-11-01 06:24:55 +0000 | [diff] [blame] | 720 | `diff` |
| 721 | ^^^^^^ |
| 722 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 723 | The attribute `diff` affects how Git generates diffs for particular |
| 724 | files. It can tell Git whether to generate a textual patch for the path |
Jeff King | 678852d | 2008-10-26 00:41:52 -0400 | [diff] [blame] | 725 | or to treat the path as a binary file. It can also affect what line is |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 726 | shown on the hunk header `@@ -k,l +n,m @@` line, tell Git to use an |
| 727 | external command to generate the diff, or ask Git to convert binary |
Jeff King | 678852d | 2008-10-26 00:41:52 -0400 | [diff] [blame] | 728 | files to a text format before generating the diff. |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 729 | |
| 730 | Set:: |
| 731 | |
| 732 | A path to which the `diff` attribute is set is treated |
| 733 | as text, even when they contain byte values that |
| 734 | normally never appear in text files, such as NUL. |
| 735 | |
| 736 | Unset:: |
| 737 | |
| 738 | A path to which the `diff` attribute is unset will |
Jeff King | 678852d | 2008-10-26 00:41:52 -0400 | [diff] [blame] | 739 | generate `Binary files differ` (or a binary patch, if |
| 740 | binary patches are enabled). |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 741 | |
| 742 | Unspecified:: |
| 743 | |
| 744 | A path to which the `diff` attribute is unspecified |
| 745 | first gets its contents inspected, and if it looks like |
Nguyễn Thái Ngọc Duy | 6bf3b81 | 2014-08-16 10:08:05 +0700 | [diff] [blame] | 746 | text and is smaller than core.bigFileThreshold, it is treated |
| 747 | as text. Otherwise it would generate `Binary files differ`. |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 748 | |
Junio C Hamano | 2cc3167 | 2007-04-23 00:21:02 -0700 | [diff] [blame] | 749 | String:: |
| 750 | |
Jeff King | 678852d | 2008-10-26 00:41:52 -0400 | [diff] [blame] | 751 | Diff is shown using the specified diff driver. Each driver may |
| 752 | specify one or more options, as described in the following |
| 753 | section. The options for the diff driver "foo" are defined |
| 754 | by the configuration variables in the "diff.foo" section of the |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 755 | Git config file. |
Junio C Hamano | 2cc3167 | 2007-04-23 00:21:02 -0700 | [diff] [blame] | 756 | |
| 757 | |
Jeff King | 678852d | 2008-10-26 00:41:52 -0400 | [diff] [blame] | 758 | Defining an external diff driver |
| 759 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Junio C Hamano | 2cc3167 | 2007-04-23 00:21:02 -0700 | [diff] [blame] | 760 | |
| 761 | The definition of a diff driver is done in `gitconfig`, not |
| 762 | `gitattributes` file, so strictly speaking this manual page is a |
| 763 | wrong place to talk about it. However... |
| 764 | |
Jeff King | 678852d | 2008-10-26 00:41:52 -0400 | [diff] [blame] | 765 | To define an external diff driver `jcdiff`, add a section to your |
Junio C Hamano | 2cc3167 | 2007-04-23 00:21:02 -0700 | [diff] [blame] | 766 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: |
| 767 | |
| 768 | ---------------------------------------------------------------- |
| 769 | [diff "jcdiff"] |
| 770 | command = j-c-diff |
| 771 | ---------------------------------------------------------------- |
| 772 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 773 | When Git needs to show you a diff for the path with `diff` |
Junio C Hamano | 2cc3167 | 2007-04-23 00:21:02 -0700 | [diff] [blame] | 774 | attribute set to `jcdiff`, it calls the command you specified |
| 775 | with the above configuration, i.e. `j-c-diff`, with 7 |
| 776 | parameters, just like `GIT_EXTERNAL_DIFF` program is called. |
Christian Couder | 9e1f0a8 | 2008-06-06 09:07:32 +0200 | [diff] [blame] | 777 | See linkgit:git[1] for details. |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 778 | |
John Cai | a4cf900 | 2023-02-20 21:04:42 +0000 | [diff] [blame] | 779 | Setting the internal diff algorithm |
| 780 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 781 | |
| 782 | The diff algorithm can be set through the `diff.algorithm` config key, but |
| 783 | sometimes it may be helpful to set the diff algorithm per path. For example, |
| 784 | one may want to use the `minimal` diff algorithm for .json files, and the |
| 785 | `histogram` for .c files, and so on without having to pass in the algorithm |
| 786 | through the command line each time. |
| 787 | |
| 788 | First, in `.gitattributes`, assign the `diff` attribute for paths. |
| 789 | |
| 790 | ------------------------ |
| 791 | *.json diff=<name> |
| 792 | ------------------------ |
| 793 | |
| 794 | Then, define a "diff.<name>.algorithm" configuration to specify the diff |
| 795 | algorithm, choosing from `myers`, `patience`, `minimal`, or `histogram`. |
| 796 | |
| 797 | ---------------------------------------------------------------- |
| 798 | [diff "<name>"] |
| 799 | algorithm = histogram |
| 800 | ---------------------------------------------------------------- |
| 801 | |
| 802 | This diff algorithm applies to user facing diff output like git-diff(1), |
| 803 | git-show(1) and is used for the `--stat` output as well. The merge machinery |
| 804 | will not use the diff algorithm set through this method. |
| 805 | |
| 806 | NOTE: If `diff.<name>.command` is defined for path with the |
| 807 | `diff=<name>` attribute, it is executed as an external diff driver |
| 808 | (see above), and adding `diff.<name>.algorithm` has no effect, as the |
| 809 | algorithm is not passed to the external diff driver. |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 810 | |
Junio C Hamano | ae7aa49 | 2007-07-08 17:15:09 -0700 | [diff] [blame] | 811 | Defining a custom hunk-header |
| 812 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 813 | |
Garry Dolley | c882c01 | 2008-09-16 23:20:39 -0700 | [diff] [blame] | 814 | Each group of changes (called a "hunk") in the textual diff output |
Junio C Hamano | ae7aa49 | 2007-07-08 17:15:09 -0700 | [diff] [blame] | 815 | is prefixed with a line of the form: |
| 816 | |
| 817 | @@ -k,l +n,m @@ TEXT |
| 818 | |
Garry Dolley | c882c01 | 2008-09-16 23:20:39 -0700 | [diff] [blame] | 819 | This is called a 'hunk header'. The "TEXT" portion is by default a line |
| 820 | that begins with an alphabet, an underscore or a dollar sign; this |
| 821 | matches what GNU 'diff -p' output uses. This default selection however |
| 822 | is not suited for some contents, and you can use a customized pattern |
| 823 | to make a selection. |
Junio C Hamano | ae7aa49 | 2007-07-08 17:15:09 -0700 | [diff] [blame] | 824 | |
Garry Dolley | c882c01 | 2008-09-16 23:20:39 -0700 | [diff] [blame] | 825 | First, in .gitattributes, you would assign the `diff` attribute |
Junio C Hamano | ae7aa49 | 2007-07-08 17:15:09 -0700 | [diff] [blame] | 826 | for paths. |
| 827 | |
| 828 | ------------------------ |
| 829 | *.tex diff=tex |
| 830 | ------------------------ |
| 831 | |
Shawn O. Pearce | edb7e82 | 2008-09-29 10:23:19 -0700 | [diff] [blame] | 832 | Then, you would define a "diff.tex.xfuncname" configuration to |
Junio C Hamano | ae7aa49 | 2007-07-08 17:15:09 -0700 | [diff] [blame] | 833 | specify a regular expression that matches a line that you would |
Jeff King | c4c86d2 | 2009-04-16 03:17:12 -0400 | [diff] [blame] | 834 | want to appear as the hunk header "TEXT". Add a section to your |
| 835 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: |
Junio C Hamano | ae7aa49 | 2007-07-08 17:15:09 -0700 | [diff] [blame] | 836 | |
| 837 | ------------------------ |
| 838 | [diff "tex"] |
Brandon Casey | 45d9414 | 2008-09-18 17:44:33 -0500 | [diff] [blame] | 839 | xfuncname = "^(\\\\(sub)*section\\{.*)$" |
Junio C Hamano | ae7aa49 | 2007-07-08 17:15:09 -0700 | [diff] [blame] | 840 | ------------------------ |
| 841 | |
| 842 | Note. A single level of backslashes are eaten by the |
| 843 | configuration file parser, so you would need to double the |
| 844 | backslashes; the pattern above picks a line that begins with a |
Brian Hetro | 0278307 | 2007-08-23 20:44:13 -0400 | [diff] [blame] | 845 | backslash, and zero or more occurrences of `sub` followed by |
Junio C Hamano | ae7aa49 | 2007-07-08 17:15:09 -0700 | [diff] [blame] | 846 | `section` followed by open brace, to the end of line. |
| 847 | |
| 848 | There are a few built-in patterns to make this easier, and `tex` |
| 849 | is one of them, so you do not have to write the above in your |
| 850 | configuration file (you still need to enable this with the |
Gustaf Hendeby | d08ed6d | 2008-08-12 16:24:25 +0200 | [diff] [blame] | 851 | attribute mechanism, via `.gitattributes`). The following built in |
| 852 | patterns are available: |
| 853 | |
Adrian Johnson | e90d065 | 2012-09-16 13:24:15 +0930 | [diff] [blame] | 854 | - `ada` suitable for source code in the Ada language. |
| 855 | |
Victor Engmark | 2ff6c34 | 2020-10-22 12:45:08 +1300 | [diff] [blame] | 856 | - `bash` suitable for source code in the Bourne-Again SHell language. |
| 857 | Covers a superset of POSIX shell function definitions. |
| 858 | |
Gustaf Hendeby | 23b5beb | 2008-08-12 16:24:26 +0200 | [diff] [blame] | 859 | - `bibtex` suitable for files with BibTeX coded references. |
| 860 | |
Thomas Rast | 80c49c3 | 2009-01-17 17:29:48 +0100 | [diff] [blame] | 861 | - `cpp` suitable for source code in the C and C++ languages. |
| 862 | |
Petr Onderka | b221207 | 2010-08-16 17:01:02 +0000 | [diff] [blame] | 863 | - `csharp` suitable for source code in the C# language. |
| 864 | |
William Duclot | 0719f3e | 2016-06-03 14:32:26 +0200 | [diff] [blame] | 865 | - `css` suitable for cascading style sheets. |
| 866 | |
Stephen Boyd | 3c81760 | 2019-08-19 14:22:43 -0700 | [diff] [blame] | 867 | - `dts` suitable for devicetree (DTS) files. |
| 868 | |
Łukasz Niemier | a807200 | 2019-11-08 22:38:24 +0100 | [diff] [blame] | 869 | - `elixir` suitable for source code in the Elixir language. |
| 870 | |
Brandon Casey | 909a549 | 2010-09-10 11:18:14 -0500 | [diff] [blame] | 871 | - `fortran` suitable for source code in the Fortran language. |
| 872 | |
Zoë Blade | 69f9c87 | 2015-07-21 14:22:46 +0100 | [diff] [blame] | 873 | - `fountain` suitable for Fountain documents. |
| 874 | |
Alban Gruin | 1dbf0c0 | 2018-03-01 12:19:07 +0100 | [diff] [blame] | 875 | - `golang` suitable for source code in the Go language. |
| 876 | |
Andreas Ericsson | af9ce1f | 2008-09-07 22:15:29 +0200 | [diff] [blame] | 877 | - `html` suitable for HTML/XHTML documents. |
| 878 | |
Ralf Wildenhues | b66e00f | 2008-09-12 21:10:26 +0200 | [diff] [blame] | 879 | - `java` suitable for source code in the Java language. |
Gustaf Hendeby | d08ed6d | 2008-08-12 16:24:25 +0200 | [diff] [blame] | 880 | |
Jaydeep P Das | 09188ed | 2022-03-12 10:18:32 +0530 | [diff] [blame] | 881 | - `kotlin` suitable for source code in the Kotlin language. |
| 882 | |
Ash Holland | 09dad92 | 2020-05-02 14:15:43 +0100 | [diff] [blame] | 883 | - `markdown` suitable for Markdown documents. |
| 884 | |
Boxuan Li | 2731a78 | 2019-05-30 00:15:39 +0800 | [diff] [blame] | 885 | - `matlab` suitable for source code in the MATLAB and Octave languages. |
Gustaf Hendeby | 53b10a1 | 2011-11-15 21:15:03 +0100 | [diff] [blame] | 886 | |
Jonathan del Strother | 5d1e958 | 2008-10-01 00:46:34 +0100 | [diff] [blame] | 887 | - `objc` suitable for source code in the Objective-C language. |
| 888 | |
Gustaf Hendeby | d08ed6d | 2008-08-12 16:24:25 +0200 | [diff] [blame] | 889 | - `pascal` suitable for source code in the Pascal/Delphi language. |
| 890 | |
Jonathan Nieder | 71a5d4b | 2010-12-26 03:07:31 -0600 | [diff] [blame] | 891 | - `perl` suitable for source code in the Perl language. |
| 892 | |
Andreas Ericsson | af9ce1f | 2008-09-07 22:15:29 +0200 | [diff] [blame] | 893 | - `php` suitable for source code in the PHP language. |
| 894 | |
Kirill Smelkov | 7c17205 | 2008-08-20 19:57:07 +0400 | [diff] [blame] | 895 | - `python` suitable for source code in the Python language. |
| 896 | |
Gustaf Hendeby | d08ed6d | 2008-08-12 16:24:25 +0200 | [diff] [blame] | 897 | - `ruby` suitable for source code in the Ruby language. |
| 898 | |
Marc-André Lureau | d74e786 | 2019-05-17 01:58:15 +0200 | [diff] [blame] | 899 | - `rust` suitable for source code in the Rust language. |
| 900 | |
Atharva Raykar | a437390 | 2021-04-08 14:44:43 +0530 | [diff] [blame] | 901 | - `scheme` suitable for source code in the Scheme language. |
| 902 | |
Gustaf Hendeby | d08ed6d | 2008-08-12 16:24:25 +0200 | [diff] [blame] | 903 | - `tex` suitable for source code for LaTeX documents. |
Junio C Hamano | ae7aa49 | 2007-07-08 17:15:09 -0700 | [diff] [blame] | 904 | |
| 905 | |
Thomas Rast | 80c49c3 | 2009-01-17 17:29:48 +0100 | [diff] [blame] | 906 | Customizing word diff |
| 907 | ^^^^^^^^^^^^^^^^^^^^^ |
| 908 | |
Thomas Rast | 882749a | 2010-04-14 17:59:06 +0200 | [diff] [blame] | 909 | You can customize the rules that `git diff --word-diff` uses to |
Thomas Rast | 80c49c3 | 2009-01-17 17:29:48 +0100 | [diff] [blame] | 910 | split words in a line, by specifying an appropriate regular expression |
Boyd Stephen Smith Jr | ae3b970 | 2009-01-20 22:59:54 -0600 | [diff] [blame] | 911 | in the "diff.*.wordRegex" configuration variable. For example, in TeX |
Thomas Rast | 80c49c3 | 2009-01-17 17:29:48 +0100 | [diff] [blame] | 912 | a backslash followed by a sequence of letters forms a command, but |
| 913 | several such commands can be run together without intervening |
Jeff King | c4c86d2 | 2009-04-16 03:17:12 -0400 | [diff] [blame] | 914 | whitespace. To separate them, use a regular expression in your |
| 915 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: |
Thomas Rast | 80c49c3 | 2009-01-17 17:29:48 +0100 | [diff] [blame] | 916 | |
| 917 | ------------------------ |
| 918 | [diff "tex"] |
Boyd Stephen Smith Jr | ae3b970 | 2009-01-20 22:59:54 -0600 | [diff] [blame] | 919 | wordRegex = "\\\\[a-zA-Z]+|[{}]|\\\\.|[^\\{}[:space:]]+" |
Thomas Rast | 80c49c3 | 2009-01-17 17:29:48 +0100 | [diff] [blame] | 920 | ------------------------ |
| 921 | |
| 922 | A built-in pattern is provided for all languages listed in the |
| 923 | previous section. |
| 924 | |
| 925 | |
Jeff King | 678852d | 2008-10-26 00:41:52 -0400 | [diff] [blame] | 926 | Performing text diffs of binary files |
| 927 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 928 | |
| 929 | Sometimes it is desirable to see the diff of a text-converted |
| 930 | version of some binary files. For example, a word processor |
| 931 | document can be converted to an ASCII text representation, and |
| 932 | the diff of the text shown. Even though this conversion loses |
| 933 | some information, the resulting diff is useful for human |
| 934 | viewing (but cannot be applied directly). |
| 935 | |
| 936 | The `textconv` config option is used to define a program for |
| 937 | performing such a conversion. The program should take a single |
| 938 | argument, the name of a file to convert, and produce the |
| 939 | resulting text on stdout. |
| 940 | |
| 941 | For example, to show the diff of the exif information of a |
| 942 | file instead of the binary information (assuming you have the |
Jeff King | c4c86d2 | 2009-04-16 03:17:12 -0400 | [diff] [blame] | 943 | exif tool installed), add the following section to your |
| 944 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file): |
Jeff King | 678852d | 2008-10-26 00:41:52 -0400 | [diff] [blame] | 945 | |
| 946 | ------------------------ |
| 947 | [diff "jpg"] |
| 948 | textconv = exif |
| 949 | ------------------------ |
| 950 | |
| 951 | NOTE: The text conversion is generally a one-way conversion; |
| 952 | in this example, we lose the actual image contents and focus |
| 953 | just on the text data. This means that diffs generated by |
| 954 | textconv are _not_ suitable for applying. For this reason, |
| 955 | only `git diff` and the `git log` family of commands (i.e., |
| 956 | log, whatchanged, show) will perform text conversion. `git |
| 957 | format-patch` will never generate this output. If you want to |
| 958 | send somebody a text-converted diff of a binary file (e.g., |
| 959 | because it quickly conveys the changes you have made), you |
| 960 | should generate it separately and send it as a comment _in |
| 961 | addition to_ the usual binary diff that you might send. |
| 962 | |
Jeff King | d9bae1a | 2010-04-01 20:12:15 -0400 | [diff] [blame] | 963 | Because text conversion can be slow, especially when doing a |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 964 | large number of them with `git log -p`, Git provides a mechanism |
Jeff King | d9bae1a | 2010-04-01 20:12:15 -0400 | [diff] [blame] | 965 | to cache the output and use it in future diffs. To enable |
| 966 | caching, set the "cachetextconv" variable in your diff driver's |
| 967 | config. For example: |
| 968 | |
| 969 | ------------------------ |
| 970 | [diff "jpg"] |
| 971 | textconv = exif |
| 972 | cachetextconv = true |
| 973 | ------------------------ |
| 974 | |
| 975 | This will cache the result of running "exif" on each blob |
| 976 | indefinitely. If you change the textconv config variable for a |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 977 | diff driver, Git will automatically invalidate the cache entries |
Jeff King | d9bae1a | 2010-04-01 20:12:15 -0400 | [diff] [blame] | 978 | and re-run the textconv filter. If you want to invalidate the |
| 979 | cache manually (e.g., because your version of "exif" was updated |
| 980 | and now produces better output), you can remove the cache |
| 981 | manually with `git update-ref -d refs/notes/textconv/jpg` (where |
| 982 | "jpg" is the name of the diff driver, as in the example above). |
Jeff King | 678852d | 2008-10-26 00:41:52 -0400 | [diff] [blame] | 983 | |
Jeff King | 55601c6 | 2011-05-24 15:45:27 -0400 | [diff] [blame] | 984 | Choosing textconv versus external diff |
| 985 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 986 | |
| 987 | If you want to show differences between binary or specially-formatted |
| 988 | blobs in your repository, you can choose to use either an external diff |
| 989 | command, or to use textconv to convert them to a diff-able text format. |
| 990 | Which method you choose depends on your exact situation. |
| 991 | |
| 992 | The advantage of using an external diff command is flexibility. You are |
| 993 | not bound to find line-oriented changes, nor is it necessary for the |
| 994 | output to resemble unified diff. You are free to locate and report |
| 995 | changes in the most appropriate way for your data format. |
| 996 | |
| 997 | A textconv, by comparison, is much more limiting. You provide a |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 998 | transformation of the data into a line-oriented text format, and Git |
Jeff King | 55601c6 | 2011-05-24 15:45:27 -0400 | [diff] [blame] | 999 | uses its regular diff tools to generate the output. There are several |
| 1000 | advantages to choosing this method: |
| 1001 | |
| 1002 | 1. Ease of use. It is often much simpler to write a binary to text |
| 1003 | transformation than it is to perform your own diff. In many cases, |
| 1004 | existing programs can be used as textconv filters (e.g., exif, |
| 1005 | odt2txt). |
| 1006 | |
| 1007 | 2. Git diff features. By performing only the transformation step |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1008 | yourself, you can still utilize many of Git's diff features, |
Jeff King | 55601c6 | 2011-05-24 15:45:27 -0400 | [diff] [blame] | 1009 | including colorization, word-diff, and combined diffs for merges. |
| 1010 | |
| 1011 | 3. Caching. Textconv caching can speed up repeated diffs, such as those |
| 1012 | you might trigger by running `git log -p`. |
| 1013 | |
| 1014 | |
Jeff King | ab43561 | 2011-01-09 15:10:04 -0500 | [diff] [blame] | 1015 | Marking files as binary |
| 1016 | ^^^^^^^^^^^^^^^^^^^^^^^ |
| 1017 | |
| 1018 | Git usually guesses correctly whether a blob contains text or binary |
| 1019 | data by examining the beginning of the contents. However, sometimes you |
| 1020 | may want to override its decision, either because a blob contains binary |
| 1021 | data later in the file, or because the content, while technically |
| 1022 | composed of text characters, is opaque to a human reader. For example, |
Thomas Ackermann | f745acb | 2014-11-03 21:37:07 +0100 | [diff] [blame] | 1023 | many postscript files contain only ASCII characters, but produce noisy |
Jeff King | ab43561 | 2011-01-09 15:10:04 -0500 | [diff] [blame] | 1024 | and meaningless diffs. |
| 1025 | |
| 1026 | The simplest way to mark a file as binary is to unset the diff |
| 1027 | attribute in the `.gitattributes` file: |
| 1028 | |
| 1029 | ------------------------ |
| 1030 | *.ps -diff |
| 1031 | ------------------------ |
| 1032 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1033 | This will cause Git to generate `Binary files differ` (or a binary |
Jeff King | ab43561 | 2011-01-09 15:10:04 -0500 | [diff] [blame] | 1034 | patch, if binary patches are enabled) instead of a regular diff. |
| 1035 | |
| 1036 | However, one may also want to specify other diff driver attributes. For |
| 1037 | example, you might want to use `textconv` to convert postscript files to |
Thomas Ackermann | f745acb | 2014-11-03 21:37:07 +0100 | [diff] [blame] | 1038 | an ASCII representation for human viewing, but otherwise treat them as |
Jeff King | ab43561 | 2011-01-09 15:10:04 -0500 | [diff] [blame] | 1039 | binary files. You cannot specify both `-diff` and `diff=ps` attributes. |
| 1040 | The solution is to use the `diff.*.binary` config option: |
| 1041 | |
| 1042 | ------------------------ |
| 1043 | [diff "ps"] |
| 1044 | textconv = ps2ascii |
| 1045 | binary = true |
| 1046 | ------------------------ |
| 1047 | |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 1048 | Performing a three-way merge |
| 1049 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1050 | |
Jakub Narebski | 4f73e24 | 2008-11-01 06:24:55 +0000 | [diff] [blame] | 1051 | `merge` |
| 1052 | ^^^^^^^ |
| 1053 | |
Alexei Sholik | b547ce0 | 2011-03-18 15:14:27 +0200 | [diff] [blame] | 1054 | The attribute `merge` affects how three versions of a file are |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 1055 | merged when a file-level merge is necessary during `git merge`, |
Ori Avtalion | 57f6ec0 | 2009-08-07 17:24:21 +0300 | [diff] [blame] | 1056 | and other commands such as `git revert` and `git cherry-pick`. |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 1057 | |
| 1058 | Set:: |
| 1059 | |
| 1060 | Built-in 3-way merge driver is used to merge the |
Jonathan Nieder | 2fd02c9 | 2008-07-03 00:55:07 -0500 | [diff] [blame] | 1061 | contents in a way similar to 'merge' command of `RCS` |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 1062 | suite. This is suitable for ordinary text files. |
| 1063 | |
| 1064 | Unset:: |
| 1065 | |
| 1066 | Take the version from the current branch as the |
| 1067 | tentative merge result, and declare that the merge has |
Alexei Sholik | b547ce0 | 2011-03-18 15:14:27 +0200 | [diff] [blame] | 1068 | conflicts. This is suitable for binary files that do |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 1069 | not have a well-defined merge semantics. |
| 1070 | |
| 1071 | Unspecified:: |
| 1072 | |
| 1073 | By default, this uses the same built-in 3-way merge |
Alexei Sholik | b547ce0 | 2011-03-18 15:14:27 +0200 | [diff] [blame] | 1074 | driver as is the case when the `merge` attribute is set. |
| 1075 | However, the `merge.default` configuration variable can name |
| 1076 | different merge driver to be used with paths for which the |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 1077 | `merge` attribute is unspecified. |
| 1078 | |
Junio C Hamano | 2cc3167 | 2007-04-23 00:21:02 -0700 | [diff] [blame] | 1079 | String:: |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 1080 | |
| 1081 | 3-way merge is performed using the specified custom |
| 1082 | merge driver. The built-in 3-way merge driver can be |
| 1083 | explicitly specified by asking for "text" driver; the |
| 1084 | built-in "take the current branch" driver can be |
Junio C Hamano | b9d14ff | 2007-04-24 13:46:02 -0700 | [diff] [blame] | 1085 | requested with "binary". |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 1086 | |
| 1087 | |
Junio C Hamano | 0e545f7 | 2007-12-22 23:14:59 -0800 | [diff] [blame] | 1088 | Built-in merge drivers |
| 1089 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 1090 | |
| 1091 | There are a few built-in low-level merge drivers defined that |
| 1092 | can be asked for via the `merge` attribute. |
| 1093 | |
| 1094 | text:: |
| 1095 | |
| 1096 | Usual 3-way file level merge for text files. Conflicted |
| 1097 | regions are marked with conflict markers `<<<<<<<`, |
| 1098 | `=======` and `>>>>>>>`. The version from your branch |
| 1099 | appears before the `=======` marker, and the version |
| 1100 | from the merged branch appears after the `=======` |
| 1101 | marker. |
| 1102 | |
| 1103 | binary:: |
| 1104 | |
| 1105 | Keep the version from your branch in the work tree, but |
| 1106 | leave the path in the conflicted state for the user to |
| 1107 | sort out. |
| 1108 | |
| 1109 | union:: |
| 1110 | |
| 1111 | Run 3-way file level merge for text files, but take |
| 1112 | lines from both versions, instead of leaving conflict |
| 1113 | markers. This tends to leave the added lines in the |
| 1114 | resulting file in random order and the user should |
| 1115 | verify the result. Do not use this if you do not |
| 1116 | understand the implications. |
| 1117 | |
| 1118 | |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 1119 | Defining a custom merge driver |
| 1120 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 1121 | |
Junio C Hamano | 0e545f7 | 2007-12-22 23:14:59 -0800 | [diff] [blame] | 1122 | The definition of a merge driver is done in the `.git/config` |
| 1123 | file, not in the `gitattributes` file, so strictly speaking this |
| 1124 | manual page is a wrong place to talk about it. However... |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 1125 | |
| 1126 | To define a custom merge driver `filfre`, add a section to your |
| 1127 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: |
| 1128 | |
| 1129 | ---------------------------------------------------------------- |
| 1130 | [merge "filfre"] |
| 1131 | name = feel-free merge driver |
Junio C Hamano | ef45bb1 | 2015-06-04 15:10:29 -0700 | [diff] [blame] | 1132 | driver = filfre %O %A %B %L %P |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 1133 | recursive = binary |
| 1134 | ---------------------------------------------------------------- |
| 1135 | |
| 1136 | The `merge.*.name` variable gives the driver a human-readable |
| 1137 | name. |
| 1138 | |
| 1139 | The `merge.*.driver` variable's value is used to construct a |
Antonin Delpeuch | 81effe9 | 2024-01-24 20:09:11 +0000 | [diff] [blame] | 1140 | command to run to common ancestor's version (`%O`), current |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 1141 | version (`%A`) and the other branches' version (`%B`). These |
| 1142 | three tokens are replaced with the names of temporary files that |
| 1143 | hold the contents of these versions when the command line is |
Antonin Delpeuch | 81effe9 | 2024-01-24 20:09:11 +0000 | [diff] [blame] | 1144 | built. Additionally, `%L` will be replaced with the conflict marker |
Bert Wesarg | 1675862 | 2010-02-23 21:11:12 +0100 | [diff] [blame] | 1145 | size (see below). |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 1146 | |
| 1147 | The merge driver is expected to leave the result of the merge in |
| 1148 | the file named with `%A` by overwriting it, and exit with zero |
| 1149 | status if it managed to merge them cleanly, or non-zero if there |
Junio C Hamano | 2b7b788 | 2023-06-22 17:33:01 -0700 | [diff] [blame] | 1150 | were conflicts. When the driver crashes (e.g. killed by SEGV), |
| 1151 | it is expected to exit with non-zero status that are higher than |
| 1152 | 128, and in such a case, the merge results in a failure (which is |
| 1153 | different from producing a conflict). |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 1154 | |
| 1155 | The `merge.*.recursive` variable specifies what other merge |
| 1156 | driver to use when the merge driver is called for an internal |
| 1157 | merge between common ancestors, when there are more than one. |
| 1158 | When left unspecified, the driver itself is used for both |
| 1159 | internal merge and the final merge. |
| 1160 | |
Junio C Hamano | ef45bb1 | 2015-06-04 15:10:29 -0700 | [diff] [blame] | 1161 | The merge driver can learn the pathname in which the merged result |
Antonin Delpeuch | 81effe9 | 2024-01-24 20:09:11 +0000 | [diff] [blame] | 1162 | will be stored via placeholder `%P`. The conflict labels to be used |
| 1163 | for the common ancestor, local head and other head can be passed by |
| 1164 | using '%S', '%X' and '%Y` respectively. |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 1165 | |
Junio C Hamano | 4c73480 | 2010-01-20 23:49:27 -0800 | [diff] [blame] | 1166 | `conflict-marker-size` |
| 1167 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 1168 | |
| 1169 | This attribute controls the length of conflict markers left in |
Štěpán Němec | 97509a3 | 2023-10-05 11:00:51 +0200 | [diff] [blame] | 1170 | the work tree file during a conflicted merge. Only a positive |
| 1171 | integer has a meaningful effect. |
Junio C Hamano | 4c73480 | 2010-01-20 23:49:27 -0800 | [diff] [blame] | 1172 | |
| 1173 | For example, this line in `.gitattributes` can be used to tell the merge |
| 1174 | machinery to leave much longer (instead of the usual 7-character-long) |
| 1175 | conflict markers when merging the file `Documentation/git-merge.txt` |
| 1176 | results in a conflict. |
| 1177 | |
| 1178 | ------------------------ |
| 1179 | Documentation/git-merge.txt conflict-marker-size=32 |
| 1180 | ------------------------ |
| 1181 | |
| 1182 | |
Junio C Hamano | cf1b786 | 2007-12-06 00:14:14 -0800 | [diff] [blame] | 1183 | Checking whitespace errors |
| 1184 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1185 | |
| 1186 | `whitespace` |
| 1187 | ^^^^^^^^^^^^ |
| 1188 | |
| 1189 | The `core.whitespace` configuration variable allows you to define what |
Jonathan Nieder | 2fd02c9 | 2008-07-03 00:55:07 -0500 | [diff] [blame] | 1190 | 'diff' and 'apply' should consider whitespace errors for all paths in |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 1191 | the project (See linkgit:git-config[1]). This attribute gives you finer |
Junio C Hamano | cf1b786 | 2007-12-06 00:14:14 -0800 | [diff] [blame] | 1192 | control per path. |
| 1193 | |
| 1194 | Set:: |
| 1195 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1196 | Notice all types of potential whitespace errors known to Git. |
Johannes Sixt | f4b05a4 | 2010-11-30 09:29:11 +0100 | [diff] [blame] | 1197 | The tab width is taken from the value of the `core.whitespace` |
| 1198 | configuration variable. |
Junio C Hamano | cf1b786 | 2007-12-06 00:14:14 -0800 | [diff] [blame] | 1199 | |
| 1200 | Unset:: |
| 1201 | |
| 1202 | Do not notice anything as error. |
| 1203 | |
| 1204 | Unspecified:: |
| 1205 | |
Johannes Sixt | f4b05a4 | 2010-11-30 09:29:11 +0100 | [diff] [blame] | 1206 | Use the value of the `core.whitespace` configuration variable to |
Junio C Hamano | cf1b786 | 2007-12-06 00:14:14 -0800 | [diff] [blame] | 1207 | decide what to notice as error. |
| 1208 | |
| 1209 | String:: |
| 1210 | |
Andrei Rybak | f955264 | 2022-12-27 22:01:56 +0100 | [diff] [blame] | 1211 | Specify a comma separated list of common whitespace problems to |
Johannes Sixt | f4b05a4 | 2010-11-30 09:29:11 +0100 | [diff] [blame] | 1212 | notice in the same format as the `core.whitespace` configuration |
Junio C Hamano | cf1b786 | 2007-12-06 00:14:14 -0800 | [diff] [blame] | 1213 | variable. |
| 1214 | |
| 1215 | |
Junio C Hamano | 8a33dd8 | 2008-07-05 18:14:27 -0700 | [diff] [blame] | 1216 | Creating an archive |
| 1217 | ~~~~~~~~~~~~~~~~~~~ |
| 1218 | |
Junio C Hamano | 08b51f5 | 2008-07-05 18:33:16 -0700 | [diff] [blame] | 1219 | `export-ignore` |
| 1220 | ^^^^^^^^^^^^^^^ |
| 1221 | |
| 1222 | Files and directories with the attribute `export-ignore` won't be added to |
| 1223 | archive files. |
| 1224 | |
Junio C Hamano | 8a33dd8 | 2008-07-05 18:14:27 -0700 | [diff] [blame] | 1225 | `export-subst` |
| 1226 | ^^^^^^^^^^^^^^ |
| 1227 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1228 | If the attribute `export-subst` is set for a file then Git will expand |
Junio C Hamano | 8a33dd8 | 2008-07-05 18:14:27 -0700 | [diff] [blame] | 1229 | several placeholders when adding this file to an archive. The |
Junio C Hamano | 08b51f5 | 2008-07-05 18:33:16 -0700 | [diff] [blame] | 1230 | expansion depends on the availability of a commit ID, i.e., if |
Junio C Hamano | 8a33dd8 | 2008-07-05 18:14:27 -0700 | [diff] [blame] | 1231 | linkgit:git-archive[1] has been given a tree instead of a commit or a |
| 1232 | tag then no replacement will be done. The placeholders are the same |
| 1233 | as those for the option `--pretty=format:` of linkgit:git-log[1], |
| 1234 | except that they need to be wrapped like this: `$Format:PLACEHOLDERS$` |
| 1235 | in the file. E.g. the string `$Format:%H$` will be replaced by the |
René Scharfe | 9609972 | 2021-02-28 12:22:47 +0100 | [diff] [blame] | 1236 | commit hash. However, only one `%(describe)` placeholder is expanded |
| 1237 | per archive to avoid denial-of-service attacks. |
Junio C Hamano | 8a33dd8 | 2008-07-05 18:14:27 -0700 | [diff] [blame] | 1238 | |
| 1239 | |
Nasser Grainawi | 975457f | 2009-10-21 14:06:21 -0700 | [diff] [blame] | 1240 | Packing objects |
| 1241 | ~~~~~~~~~~~~~~~ |
| 1242 | |
| 1243 | `delta` |
| 1244 | ^^^^^^^ |
| 1245 | |
| 1246 | Delta compression will not be attempted for blobs for paths with the |
| 1247 | attribute `delta` set to false. |
| 1248 | |
| 1249 | |
Alexander Gavrilov | a2df1fb | 2008-11-13 20:28:49 +0300 | [diff] [blame] | 1250 | Viewing files in GUI tools |
| 1251 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1252 | |
| 1253 | `encoding` |
| 1254 | ^^^^^^^^^^ |
| 1255 | |
| 1256 | The value of this attribute specifies the character encoding that should |
| 1257 | be used by GUI tools (e.g. linkgit:gitk[1] and linkgit:git-gui[1]) to |
| 1258 | display the contents of the relevant file. Note that due to performance |
| 1259 | considerations linkgit:gitk[1] does not use this attribute unless you |
| 1260 | manually enable per-file encodings in its options. |
| 1261 | |
| 1262 | If this attribute is not set or has an invalid value, the value of the |
| 1263 | `gui.encoding` configuration variable is used instead |
| 1264 | (See linkgit:git-config[1]). |
| 1265 | |
| 1266 | |
Michael Haggerty | 0922570 | 2011-08-03 15:41:30 +0200 | [diff] [blame] | 1267 | USING MACRO ATTRIBUTES |
Junio C Hamano | bbb896d | 2008-08-30 14:35:15 -0700 | [diff] [blame] | 1268 | ---------------------- |
| 1269 | |
| 1270 | You do not want any end-of-line conversions applied to, nor textual diffs |
| 1271 | produced for, any binary file you track. You would need to specify e.g. |
| 1272 | |
| 1273 | ------------ |
Eyvind Bernhardsen | 5ec3e67 | 2010-05-19 22:43:11 +0200 | [diff] [blame] | 1274 | *.jpg -text -diff |
Junio C Hamano | bbb896d | 2008-08-30 14:35:15 -0700 | [diff] [blame] | 1275 | ------------ |
| 1276 | |
| 1277 | but that may become cumbersome, when you have many attributes. Using |
Michael Haggerty | 0922570 | 2011-08-03 15:41:30 +0200 | [diff] [blame] | 1278 | macro attributes, you can define an attribute that, when set, also |
Michael Haggerty | 98e8406 | 2011-08-03 15:41:29 +0200 | [diff] [blame] | 1279 | sets or unsets a number of other attributes at the same time. The |
Michael Haggerty | 0922570 | 2011-08-03 15:41:30 +0200 | [diff] [blame] | 1280 | system knows a built-in macro attribute, `binary`: |
Junio C Hamano | bbb896d | 2008-08-30 14:35:15 -0700 | [diff] [blame] | 1281 | |
| 1282 | ------------ |
| 1283 | *.jpg binary |
| 1284 | ------------ |
| 1285 | |
Michael Haggerty | 98e8406 | 2011-08-03 15:41:29 +0200 | [diff] [blame] | 1286 | Setting the "binary" attribute also unsets the "text" and "diff" |
Michael Haggerty | 0922570 | 2011-08-03 15:41:30 +0200 | [diff] [blame] | 1287 | attributes as above. Note that macro attributes can only be "Set", |
Michael Haggerty | 98e8406 | 2011-08-03 15:41:29 +0200 | [diff] [blame] | 1288 | though setting one might have the effect of setting or unsetting other |
| 1289 | attributes or even returning other attributes to the "Unspecified" |
| 1290 | state. |
Junio C Hamano | bbb896d | 2008-08-30 14:35:15 -0700 | [diff] [blame] | 1291 | |
| 1292 | |
Michael Haggerty | 0922570 | 2011-08-03 15:41:30 +0200 | [diff] [blame] | 1293 | DEFINING MACRO ATTRIBUTES |
Junio C Hamano | bbb896d | 2008-08-30 14:35:15 -0700 | [diff] [blame] | 1294 | ------------------------- |
| 1295 | |
Michael Haggerty | e78e696 | 2014-01-14 03:58:49 +0100 | [diff] [blame] | 1296 | Custom macro attributes can be defined only in top-level gitattributes |
| 1297 | files (`$GIT_DIR/info/attributes`, the `.gitattributes` file at the |
| 1298 | top level of the working tree, or the global or system-wide |
| 1299 | gitattributes files), not in `.gitattributes` files in working tree |
| 1300 | subdirectories. The built-in macro attribute "binary" is equivalent |
| 1301 | to: |
Junio C Hamano | bbb896d | 2008-08-30 14:35:15 -0700 | [diff] [blame] | 1302 | |
| 1303 | ------------ |
Junio C Hamano | 155a4b7 | 2012-09-08 21:28:55 -0700 | [diff] [blame] | 1304 | [attr]binary -diff -merge -text |
Junio C Hamano | bbb896d | 2008-08-30 14:35:15 -0700 | [diff] [blame] | 1305 | ------------ |
| 1306 | |
Jeff King | 8ff06de | 2021-05-03 16:43:28 -0400 | [diff] [blame] | 1307 | NOTES |
| 1308 | ----- |
| 1309 | |
| 1310 | Git does not follow symbolic links when accessing a `.gitattributes` |
| 1311 | file in the working tree. This keeps behavior consistent when the file |
| 1312 | is accessed from the index or a tree versus from the filesystem. |
Junio C Hamano | bbb896d | 2008-08-30 14:35:15 -0700 | [diff] [blame] | 1313 | |
Nguyễn Thái Ngọc Duy | 76a8788 | 2018-04-30 17:35:33 +0200 | [diff] [blame] | 1314 | EXAMPLES |
| 1315 | -------- |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 1316 | |
| 1317 | If you have these three `gitattributes` file: |
| 1318 | |
| 1319 | ---------------------------------------------------------------- |
| 1320 | (in $GIT_DIR/info/attributes) |
| 1321 | |
| 1322 | a* foo !bar -baz |
| 1323 | |
| 1324 | (in .gitattributes) |
| 1325 | abc foo bar baz |
| 1326 | |
| 1327 | (in t/.gitattributes) |
| 1328 | ab* merge=filfre |
| 1329 | abc -foo -bar |
| 1330 | *.c frotz |
| 1331 | ---------------------------------------------------------------- |
| 1332 | |
| 1333 | the attributes given to path `t/abc` are computed as follows: |
| 1334 | |
| 1335 | 1. By examining `t/.gitattributes` (which is in the same |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 1336 | directory as the path in question), Git finds that the first |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 1337 | line matches. `merge` attribute is set. It also finds that |
| 1338 | the second line matches, and attributes `foo` and `bar` |
| 1339 | are unset. |
| 1340 | |
| 1341 | 2. Then it examines `.gitattributes` (which is in the parent |
| 1342 | directory), and finds that the first line matches, but |
| 1343 | `t/.gitattributes` file already decided how `merge`, `foo` |
| 1344 | and `bar` attributes should be given to this path, so it |
| 1345 | leaves `foo` and `bar` unset. Attribute `baz` is set. |
| 1346 | |
David Soria Parra | 5c759f9 | 2007-07-29 22:50:24 -0300 | [diff] [blame] | 1347 | 3. Finally it examines `$GIT_DIR/info/attributes`. This file |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 1348 | is used to override the in-tree settings. The first line is |
| 1349 | a match, and `foo` is set, `bar` is reverted to unspecified |
| 1350 | state, and `baz` is unset. |
| 1351 | |
Brian Hetro | 0278307 | 2007-08-23 20:44:13 -0400 | [diff] [blame] | 1352 | As the result, the attributes assignment to `t/abc` becomes: |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 1353 | |
| 1354 | ---------------------------------------------------------------- |
| 1355 | foo set to true |
| 1356 | bar unspecified |
| 1357 | baz set to false |
| 1358 | merge set to string value "filfre" |
| 1359 | frotz unspecified |
| 1360 | ---------------------------------------------------------------- |
| 1361 | |
| 1362 | |
Michael Haggerty | cde1518 | 2011-08-04 06:36:11 +0200 | [diff] [blame] | 1363 | SEE ALSO |
| 1364 | -------- |
| 1365 | linkgit:git-check-attr[1]. |
René Scharfe | 8460b2f | 2007-09-03 20:07:01 +0200 | [diff] [blame] | 1366 | |
Junio C Hamano | 88e7fdf | 2007-04-19 20:48:03 -0700 | [diff] [blame] | 1367 | GIT |
| 1368 | --- |
Christian Couder | 9e1f0a8 | 2008-06-06 09:07:32 +0200 | [diff] [blame] | 1369 | Part of the linkgit:git[1] suite |