Merge branch 'rh/diff-orderfile-doc'
authorJunio C Hamano <gitster@pobox.com>
Mon, 23 Jan 2017 23:59:23 +0000 (15:59 -0800)
committerJunio C Hamano <gitster@pobox.com>
Mon, 23 Jan 2017 23:59:23 +0000 (15:59 -0800)
Documentation fix.

* rh/diff-orderfile-doc:
diff: document the format of the -O (diff.orderFile) file
diff: document behavior of relative diff.orderFile

1  2 
Documentation/diff-config.txt
Documentation/diff-options.txt
index 15521f5191b6fdba66c2d3d4f92491dd8c4524f3,85aca8bbe865514b1920670ed281c1a6a8ab59f3..cbce8ec63841e8631f7122dae6e084b15e16832d
@@@ -60,12 -60,6 +60,12 @@@ diff.context:
        Generate diffs with <n> lines of context instead of the default
        of 3. This value is overridden by the -U option.
  
 +diff.interHunkContext::
 +      Show the context between diff hunks, up to the specified number
 +      of lines, thereby fusing the hunks that are close to each other.
 +      This value serves as the default for the `--inter-hunk-context`
 +      command line option.
 +
  diff.external::
        If this config variable is set, diff generation is not
        performed using the internal diff machinery, but using the
@@@ -105,9 -99,10 +105,10 @@@ diff.noprefix:
        If set, 'git diff' does not show any source or destination prefix.
  
  diff.orderFile::
-       File indicating how to order files within a diff, using
-       one shell glob pattern per line.
-       Can be overridden by the '-O' option to linkgit:git-diff[1].
+       File indicating how to order files within a diff.
+       See the '-O' option to linkgit:git-diff[1] for details.
+       If `diff.orderFile` is a relative pathname, it is treated as
+       relative to the top of the working tree.
  
  diff.renameLimit::
        The number of files to consider when performing the copy/rename
@@@ -178,8 -173,10 +179,8 @@@ diff.tool:
  include::mergetools-diff.txt[]
  
  diff.indentHeuristic::
 -diff.compactionHeuristic::
 -      Set one of these options to `true` to enable one of two
 -      experimental heuristics that shift diff hunk boundaries to
 -      make patches easier to read.
 +      Set this option to `true` to enable experimental heuristics
 +      that shift diff hunk boundaries to make patches easier to read.
  
  diff.algorithm::
        Choose a diff algorithm.  The variants are as follows:
index a219aa290726d504e7b4c7ec0a3051e091b5445b,d4fb70704482fd18bb981be35607b682c069b820..d91ddbd5fe490527bd3032789d0bf3f2eef93f93
@@@ -466,11 -466,41 +466,41 @@@ information
  endif::git-format-patch[]
  
  -O<orderfile>::
-       Output the patch in the order specified in the
-       <orderfile>, which has one shell glob pattern per line.
+       Control the order in which files appear in the output.
        This overrides the `diff.orderFile` configuration variable
        (see linkgit:git-config[1]).  To cancel `diff.orderFile`,
        use `-O/dev/null`.
+ +
+ The output order is determined by the order of glob patterns in
+ <orderfile>.
+ All files with pathnames that match the first pattern are output
+ first, all files with pathnames that match the second pattern (but not
+ the first) are output next, and so on.
+ All files with pathnames that do not match any pattern are output
+ last, as if there was an implicit match-all pattern at the end of the
+ file.
+ If multiple pathnames have the same rank (they match the same pattern
+ but no earlier patterns), their output order relative to each other is
+ the normal order.
+ +
+ <orderfile> is parsed as follows:
+ +
+ --
+  - Blank lines are ignored, so they can be used as separators for
+    readability.
+  - Lines starting with a hash ("`#`") are ignored, so they can be used
+    for comments.  Add a backslash ("`\`") to the beginning of the
+    pattern if it starts with a hash.
+  - Each other line contains a single pattern.
+ --
+ +
+ Patterns have the same syntax and semantics as patterns used for
+ fnmantch(3) without the FNM_PATHNAME flag, except a pathname also
+ matches a pattern if removing any number of the final pathname
+ components matches the pattern.  For example, the pattern "`foo*bar`"
+ matches "`fooasdfbar`" and "`foo/bar/baz/asdf`" but not "`foobarx`".
  
  ifndef::git-format-patch[]
  -R::
@@@ -511,8 -541,6 +541,8 @@@ endif::git-format-patch[
  --inter-hunk-context=<lines>::
        Show the context between diff hunks, up to the specified number
        of lines, thereby fusing hunks that are close to each other.
 +      Defaults to `diff.interHunkContext` or 0 if the config option
 +      is unset.
  
  -W::
  --function-context::