From: Junio C Hamano <gitster@pobox.com>
Date: Mon, 23 Jan 2017 23:59:23 +0000 (-0800)
Subject: Merge branch 'rh/diff-orderfile-doc'
X-Git-Tag: v2.12.0-rc0~46
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/831bd5e775ad5225f2a98eba738f69148cd50e0a?ds=inline;hp=-c

Merge branch 'rh/diff-orderfile-doc'

Documentation fix.

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

831bd5e775ad5225f2a98eba738f69148cd50e0a
diff --combined Documentation/diff-config.txt
index 15521f5191,85aca8bbe8..cbce8ec638
--- a/Documentation/diff-config.txt
+++ b/Documentation/diff-config.txt
@@@ -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:
diff --combined Documentation/diff-options.txt
index a219aa2907,d4fb707044..d91ddbd5fe
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@@ -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::