@matheusbsbs / matheus-bagliano / commits / ae7aa49914
Fork 0

Document custom hunk header selection

Since the external interface seems to have stabilized for this new feature, let's document it properly. Acked-by: Johannes Schindelin <Johannes.Schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Junio C Hamano committed Jul 8, 2007 at 17:15 UTC ae7aa49914072b9007ba62245e68b8bbd24f964a
1 file changed +51 -4
Documentation/gitattributes.txt
+51 -4
@@ -72,8 +72,8 @@ EFFECTS
72 -------
73
74 Certain operations by git can be influenced by assigning
75 -particular attributes to a path. Currently, three operations
76 -are attributes-aware.
75 +particular attributes to a path. Currently, the following
76 +operations are attributes-aware.
77
78 Checking-out and checking-in
79 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -199,7 +199,9 @@ Generating diff text
199 ~~~~~~~~~~~~~~~~~~~~
200
201 The attribute `diff` affects if `git diff` generates textual
202 -patch for the path or just says `Binary files differ`.
202 +patch for the path or just says `Binary files differ`. It also
203 +can affect what line is shown on the hunk header `@@ -k,l +n,m @@`
204 +line.
205
206 Set::
207
@@ -224,7 +226,8 @@ String::
226 Diff is shown using the specified custom diff driver.
227 The driver program is given its input using the same
228 calling convention as used for GIT_EXTERNAL_DIFF
227 - program.
229 + program. This name is also used for custom hunk header
230 + selection.
231
232
233 Defining a custom diff driver
@@ -249,6 +252,50 @@ parameters, just like `GIT_EXTERNAL_DIFF` program is called.
252 See gitlink:git[7] for details.
253
254
255 +Defining a custom hunk-header
256 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
257 +
258 +Each group of changes (called "hunk") in the textual diff output
259 +is prefixed with a line of the form:
260 +
261 + @@ -k,l +n,m @@ TEXT
262 +
263 +The text is called 'hunk header', and by default a line that
264 +begins with an alphabet, an underscore or a dollar sign is used,
265 +which matches what GNU `diff -p` output uses. This default
266 +selection however is not suited for some contents, and you can
267 +use customized pattern to make a selection.
268 +
269 +First in .gitattributes, you would assign the `diff` attribute
270 +for paths.
271 +
272 +------------------------
273 +*.tex diff=tex
274 +------------------------
275 +
276 +Then, you would define "diff.tex.funcname" configuration to
277 +specify a regular expression that matches a line that you would
278 +want to appear as the hunk header, like this:
279 +
280 +------------------------
281 +[diff "tex"]
282 + funcname = "^\\(\\\\\\(sub\\)*section{.*\\)$"
283 +------------------------
284 +
285 +Note. A single level of backslashes are eaten by the
286 +configuration file parser, so you would need to double the
287 +backslashes; the pattern above picks a line that begins with a
288 +backslash, and zero or more occurences of `sub` followed by
289 +`section` followed by open brace, to the end of line.
290 +
291 +There are a few built-in patterns to make this easier, and `tex`
292 +is one of them, so you do not have to write the above in your
293 +configuration file (you still need to enable this with the
294 +attribute mechanism, via `.gitattributes`). Another built-in
295 +pattern is defined for `java` that defines a pattern suitable
296 +for program text in Java language.
297 +
298 +
299 Performing a three-way merge
300 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
301