minor diff orderfile documentation improvements
cover minor diff orderfile documentation improvements
Richard Hansen (2):
diff: document behavior of relative diff.orderFile
diff: document the pattern format for diff.orderFile
Documentation/diff-config.txt | 5 ++++- Documentation/diff-options.txt | 3 ++- 2 files changed, 6 insertions(+), 2 deletions(-)
Signature · 1 line
2.11.0.390.gc69c2f50cf-goog
PATCH 1/2 diff: document behavior of relative diff.orderFile
Document that a relative pathname for diff.orderFile is interpreted as relative to the top-level work directory.
--- Documentation/diff-config.txt | 2 ++ 1 file changed, 2 insertions(+)
Documentation/diff-config.txt +2 -0
@@ -101,6 +101,8 @@ diff.noprefix:: diff.orderFile:: File indicating how to order files within a diff, using one shell glob pattern per line. + If `diff.orderFile` is a relative pathname, it is treated as + relative to the top of the work tree. Can be overridden by the '-O' option to linkgit:git-diff[1]. diff.renameLimit::
Signature · 1 line
2.11.0.390.gc69c2f50cf-goog
PATCH 2/2 diff: document the pattern format for diff.orderFile
In reply to Richard HansenDocument the format of the patterns used for the diff.orderFile setting and diff's '-O' option by referring the reader to the gitignore[5] page.
--- Documentation/diff-config.txt | 3 ++- Documentation/diff-options.txt | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-)
Documentation/diff-config.txt +2 -1
@@ -100,7 +100,8 @@ diff.noprefix:: diff.orderFile:: File indicating how to order files within a diff, using - one shell glob pattern per line. + one glob pattern per line. + See linkgit:gitignore[5] for the pattern format. If `diff.orderFile` is a relative pathname, it is treated as relative to the top of the work tree. Can be overridden by the '-O' option to linkgit:git-diff[1].
Documentation/diff-options.txt +2 -1
@@ -467,7 +467,8 @@ endif::git-format-patch[] -O<orderfile>:: Output the patch in the order specified in the - <orderfile>, which has one shell glob pattern per line. + <orderfile>, which has one glob pattern per line. + See linkgit:gitignore[5] for the pattern format. This overrides the `diff.orderFile` configuration variable (see linkgit:git-config[1]). To cancel `diff.orderFile`, use `-O/dev/null`.
Signature · 1 line
2.11.0.390.gc69c2f50cf-goog
Re: [PATCH 1/2] diff: document behavior of relative diff.orderFile
In reply to Richard HansenQuoted 13 lines · Richard Hansen
Document that a relative pathname for diff.orderFile is interpreted as relative to the top-level work directory.
Signed-off-by Richard Hansen <[email protected]>--- Documentation/diff-config.txt | 2 ++ 1 file changed, 2 insertions(+)Documentation/diff-config.txt +0
-0
Documentation/diff-config.txt diff.noprefix:: · line 106
Quoted 6 lines
Documentation/diff-config.txt +2
-0@@ -101,6 +101,8 @@ diff.noprefix:: diff.orderFile:: File indicating how to order files within a diff, using one shell glob pattern per line. + If `diff.orderFile` is a relative pathname, it is treated as + relative to the top of the work tree. Can be overridden by the '-O' option to linkgit:git-diff[1].
What happens in a bare repository?
I'm guessing it's relative to the top-level of the repository, but we should probably spell it out.
The other case is --no-index when we are not in a repository at all, but that should just be relative to the current directory, which isn't really worth mentioning.
-Peff
Re: [PATCH 1/2] diff: document behavior of relative diff.orderFile
Quoted 10 lines · Jeff King
Quoted 8 lines · Richard Hansen
Document that a relative pathname for diff.orderFile is interpreted as relative to the top-level work directory.
Signed-off-by Richard Hansen <[email protected]>--- Documentation/diff-config.txt | 2 ++ 1 file changed, 2 insertions(+)
Quoted 13 lines
Documentation/diff-config.txt diff.noprefix:: · line 106
Quoted 11 lines
Documentation/diff-config.txt +2
-0@@ -101,6 +101,8 @@ diff.noprefix:: diff.orderFile:: File indicating how to order files within a diff, using one shell glob pattern per line. + If `diff.orderFile` is a relative pathname, it is treated as + relative to the top of the work tree. Can be overridden by the '-O' option to linkgit:git-diff[1].What happens in a bare repository?
I didn't know which is why this patch is silent on that topic. :)
Quoted 2 lines
I'm guessing it's relative to the top-level of the repository,
I just tried it out and it's relative to $PWD.
Quoted 1 line
but we should probably spell it out.
Do we want it to be relative to $PWD? I think relative to $GIT_DIR is more useful. If we want it to be relative to $GIT_DIR, then I think we should stay silent regarding bare repositories so that the behavior remains unspecified until we update the logic.
Quoted 3 lines
The other case is --no-index when we are not in a repository at all, but that should just be relative to the current directory,
It is.
Quoted 1 line
which isn't really worth mentioning.
Agreed.
I'll post a re-roll if people prefer the current behavior over relative to $GIT_DIR.
Thanks for reviewing,
Richard
Quoted 2 lines
-Peff
Re: [PATCH 2/2] diff: document the pattern format for diff.orderFile
In reply to Richard HansenQuoted 15 lines · Richard Hansen
Document the format of the patterns used for the diff.orderFile setting and diff's '-O' option by referring the reader to the gitignore[5] page.
Signed-off-by Richard Hansen <[email protected]>--- Documentation/diff-config.txt | 3 ++- Documentation/diff-options.txt | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-)Documentation/diff-config.txt +0
-0
Documentation/diff-config.txt diff.noprefix:: · line 104
Quoted 6 lines
Documentation/diff-config.txt +2
-1@@ -100,7 +100,8 @@ diff.noprefix:: diff.orderFile:: File indicating how to order files within a diff, using - one shell glob pattern per line. + one glob pattern per line. + See linkgit:gitignore[5] for the pattern format.
I do not think it is wise to suggest referring to gitignore, as the logic of matching is quite different, other than the fact that they both use wildmatch() internally. Also, unlike gitignore, orderfile does not allow any negative matching i.e. "!<pattern>".
Quoted 17 lines
Documentation/diff-config.txt +0
-0If `diff.orderFile` is a relative pathname, it is treated as relative to the top of the work tree. Can be overridden by the '-O' option to linkgit:git-diff[1].Documentation/diff-options.txt +2
-1@@ -467,7 +467,8 @@ endif::git-format-patch[] -O<orderfile>:: Output the patch in the order specified in the - <orderfile>, which has one shell glob pattern per line. + <orderfile>, which has one glob pattern per line. + See linkgit:gitignore[5] for the pattern format. This overrides the `diff.orderFile` configuration variable (see linkgit:git-config[1]). To cancel `diff.orderFile`, use `-O/dev/null`.
Re: [PATCH 1/2] diff: document behavior of relative diff.orderFile
In reply to Richard HansenQuoted 7 lines · Richard Hansen
On 2017-01-10 01:58, Jeff King wrote:
...Quoted 3 lines
What happens in a bare repository?
I'm guessing it's relative to the top-level of the repository,
I just tried it out and it's relative to $PWD.
That is understandable. When the user says
$ cmd -O $file
with any option -O that takes a filename, it is most natural if we used $PWD/$file when $file is not absolute path.
Re: [PATCH 1/2] diff: document behavior of relative diff.orderFile
Quoted 8 lines · Junio C Hamano
Quoted 6 lines · Richard Hansen
On 2017-01-10 01:58, Jeff King wrote:
...Quoted 3 lines
What happens in a bare repository?
I'm guessing it's relative to the top-level of the repository,
Quoted 8 lines
Quoted 1 line
I just tried it out and it's relative to $PWD.
That is understandable. When the user says
$ cmd -O $filewith any option -O that takes a filename, it is most natural if we used $PWD/$file when $file is not absolute path.
Ahh, ignore me in the above. The discussion is about the configuration variable, and I agree that being relative to GIT_DIR would have made more sense. In fact taking it as relative to PWD does not make any sense.
We should have been a lot more careful when we added 6d8940b562 ("diff: add diff.orderfile configuration variable", 2013-12-18), but it is too late to complain now.
A related tangent.
I wonder if anything that uses git_config_pathname() should be relative to GIT_DIR when it is not absolute.
Re: [PATCH 1/2] diff: document behavior of relative diff.orderFile
Quoted 16 lines · Junio C Hamano
Quoted 14 lines · Junio C Hamano
Quoted 7 lines · Richard Hansen
On 2017-01-10 01:58, Jeff King wrote:
...Quoted 3 lines
What happens in a bare repository?
I'm guessing it's relative to the top-level of the repository,
I just tried it out and it's relative to $PWD.
That is understandable. When the user says
$ cmd -O $file
Quoted 7 lines
Quoted 2 lines
with any option -O that takes a filename, it is most natural if we used $PWD/$file when $file is not absolute path.
Ahh, ignore me in the above. The discussion is about the configuration variable, and I agree that being relative to
GIT_DIRwould have made more sense. In fact taking it as relative to PWD does not make any sense.
I'll stay silent regarding bare repositories then.
Quoted 9 lines
We should have been a lot more careful when we added
6d8940b562("diff: add diff.orderfile configuration variable", 2013-12-18), but it is too late to complain now.A related tangent.
I wonder if anything that uses
git_config_pathname()should be relative toGIT_DIRwhen it is not absolute.
I think so. (For bare repositories anyway; non-bare should be relative to GIT_WORK_TREE.) Perhaps git_config_pathname() itself should convert relative paths to absolute so that every pathname setting automatically works without changing any calling code.
-Richard
Re: [PATCH 1/2] diff: document behavior of relative diff.orderFile
Quoted 9 lines · Richard Hansen
Quoted 4 lines
A related tangent.
I wonder if anything that uses
git_config_pathname()should be relative toGIT_DIRwhen it is not absolute.I think so. (For bare repositories anyway; non-bare should be relative to
GIT_WORK_TREE.) Perhapsgit_config_pathname()itself should convert relative paths to absolute so that every pathname setting automatically works without changing any calling code.
Yes, that was what I was alluding to. We might have to wait until major version boundary to do so, but I think that it is the sensible way forward in the longer term to convert relative to absolute in git_config_pathname().
Thanks.
Re: [PATCH 2/2] diff: document the pattern format for diff.orderFile
In reply to Junio C HamanoQuoted 18 lines · Junio C Hamano
Quoted 16 lines · Richard Hansen
Document the format of the patterns used for the diff.orderFile setting and diff's '-O' option by referring the reader to the gitignore[5] page.
Signed-off-by Richard Hansen <[email protected]>--- Documentation/diff-config.txt | 3 ++- Documentation/diff-options.txt | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-)Documentation/diff-config.txt +0
-0@@ -100,7 +100,8 @@ diff.noprefix::
Quoted 11 lines
Documentation/diff-config.txt diff.noprefix:: · line 104
Quoted 5 lines
Documentation/diff-config.txt +2
-1diff.orderFile:: File indicating how to order files within a diff, using - one shell glob pattern per line. + one glob pattern per line. + See linkgit:gitignore[5] for the pattern format.I do not think it is wise to suggest referring to gitignore, as the logic of matching is quite different, other than the fact that they both use
wildmatch()internally. Also, unlike gitignore, orderfile does not allow any negative matching i.e. "!<pattern>".
I was looking at the code to see how the two file formats differed and noticed that match_order() doesn't set the WM_PATHNAME flag when it calls wildmatch(). That's unintentional (a bug), right?
-Richard
Quoted 18 lines
Quoted 18 lines
Documentation/diff-config.txt +0
-0If `diff.orderFile` is a relative pathname, it is treated as relative to the top of the work tree. Can be overridden by the '-O' option to linkgit:git-diff[1].Documentation/diff-options.txt +2
-1@@ -467,7 +467,8 @@ endif::git-format-patch[] -O<orderfile>:: Output the patch in the order specified in the - <orderfile>, which has one shell glob pattern per line. + <orderfile>, which has one glob pattern per line. + See linkgit:gitignore[5] for the pattern format. This overrides the `diff.orderFile` configuration variable (see linkgit:git-config[1]). To cancel `diff.orderFile`, use `-O/dev/null`.
v2 cover diff orderfile documentation improvements
In reply to Richard HansenChanges from v1:
* Don't reference gitignore for the file format because they're not quite the same.
Richard Hansen (2):
diff: document behavior of relative diff.orderFile
diff: document the format of the -O (diff.orderFile) file
Documentation/diff-config.txt | 7 +++--- Documentation/diff-options.txt | 54 ++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 56 insertions(+), 5 deletions(-)
Signature · 1 line
2.11.0.390.gc69c2f50cf-goog
PATCH v2 1/2 diff: document behavior of relative diff.orderFile
Document that a relative pathname for diff.orderFile is interpreted as relative to the top-level work directory.
--- Documentation/diff-config.txt | 2 ++ 1 file changed, 2 insertions(+)
Documentation/diff-config.txt +2 -0
@@ -101,6 +101,8 @@ diff.noprefix:: diff.orderFile:: File indicating how to order files within a diff, using one shell glob pattern per line. + If `diff.orderFile` is a relative pathname, it is treated as + relative to the top of the work tree. Can be overridden by the '-O' option to linkgit:git-diff[1]. diff.renameLimit::
Signature · 1 line
2.11.0.390.gc69c2f50cf-goog
PATCH v2 2/2 diff: document the format of the -O (diff.orderFile) file
In reply to Richard Hansen--- Documentation/diff-config.txt | 5 ++-- Documentation/diff-options.txt | 54 ++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 54 insertions(+), 5 deletions(-)
Documentation/diff-config.txt +2 -3
@@ -99,11 +99,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. + 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 work tree. - Can be overridden by the '-O' option to linkgit:git-diff[1]. diff.renameLimit:: The number of files to consider when performing the copy/rename
Documentation/diff-options.txt +52 -2
63 lines not on this page · raw message
Signature · 1 line
2.11.0.390.gc69c2f50cf-goog
Re: [PATCH 2/2] diff: document the pattern format for diff.orderFile
In reply to Richard HansenQuoted 3 lines · Richard Hansen
I was looking at the code to see how the two file formats differed and noticed that
match_order()doesn't set theWM_PATHNAMEflag when it callswildmatch(). That's unintentional (a bug), right?
It has been that way from day one IIRC even before we introduced wildmatch()---IOW it may be intentional that the current code that uses wildmatch() does not use WM_PATHNAME.
Re: [PATCH 1/2] diff: document behavior of relative diff.orderFile
In reply to Junio C HamanoQuoted 12 lines · Junio C Hamano
Quoted 9 lines · Richard Hansen
Quoted 4 lines
A related tangent.
I wonder if anything that uses
git_config_pathname()should be relative toGIT_DIRwhen it is not absolute.I think so. (For bare repositories anyway; non-bare should be relative to
GIT_WORK_TREE.) Perhapsgit_config_pathname()itself should convert relative paths to absolute so that every pathname setting automatically works without changing any calling code.
Quoted 4 lines
Yes, that was what I was alluding to. We might have to wait until major version boundary to do so, but I think that it is the sensible way forward in the longer term to convert relative to absolute in
git_config_pathname().
Yeah, I'd agree.
I'm undecided on whether it would need to happen at a major version bump. The existing semantics are fairly insane, and would cause a lot of confusing breakages. We can imagine use of relative paths in a bare repository falls into one of a few categories:
1. The user generally runs by "cd /path/to/bare.git && git ...". This would be unaffected, as relative and $GIT_DIR are the same.
2. The user runs via "cd /path/to/bare.git/some-subdir". This would be broken, but I have trouble imagining that they really wanted to read something like "objects/orderfile".
3. The user runs via "GIT_DIR=/path/to/bare.git" from various directories. This case is probably horribly broken, as things like diff.orderFile will complain if they ever run from a directory that doesn't have the order file.
4. They run GIT_DIR=/path/to/bare.git from a consistent origin directory. This _does_ work, and we'd be breaking it. Though I kind of question why the config in $GIT_DIR is meant to apply to a file in a totally unrelated directory.
I suppose somebody could be relying on the behavior where setting GIT_DIR uses the current directory as the working tree (i.e., if core.bare is "true" in bare.git). But then, we'd consider their working directory as the working tree and read from that anyway. So the behavior would stay the same.
So I dunno. I do hate to break even corner cases, but I'm having trouble imagining the scenario where somebody is actually using the current behavior in a useful way.
-Peff
Re: [PATCH 2/2] diff: document the pattern format for diff.orderFile
In reply to Junio C HamanoQuoted 9 lines · Junio C Hamano
Quoted 3 lines · Richard Hansen
I was looking at the code to see how the two file formats differed and noticed that
match_order()doesn't set theWM_PATHNAMEflag when it callswildmatch(). That's unintentional (a bug), right?It has been that way from day one IIRC even before we introduced wildmatch()---IOW it may be intentional that the current code that uses
wildmatch()does not useWM_PATHNAME.
You are the original author (af5323e027 2005-05-30). Do you remember what your intention was?
I would like to change it to pass WM_PATHNAME, but I'm not sure if that would break anyone. I'm guessing probably not, because users probably expect WM_PATHNAME and would be surprised (like I was) to learn otherwise.
If we want to keep it as-is, I'll have to adjust [PATCH v2 2/2].
-Richard
Re: [PATCH 2/2] diff: document the pattern format for diff.orderFile
Quoted 7 lines · Richard Hansen
Quoted 6 lines · Junio C Hamano
Quoted 3 lines · Richard Hansen
I was looking at the code to see how the two file formats differed and noticed that
match_order()doesn't set theWM_PATHNAMEflag when it callswildmatch(). That's unintentional (a bug), right?
Quoted 6 lines
Quoted 3 lines
It has been that way from day one IIRC even before we introduced wildmatch()---IOW it may be intentional that the current code that uses
wildmatch()does not useWM_PATHNAME.You are the original author (
af5323e0272005-05-30). Do you remember what your intention was?
Yes.
Back then we didn't even have wildmatch(), and used fnmatch() instead, so forcing FNM_PATHNAME would have meant that people wouldn't be able to say "foo*bar" to match "foo/other/bar"; with wildmatch, "foo**bar" lets you defeat WM_PATHNAME so having WM_PATHNAME always in effect is less of an issue, but with fnmatch(), having FNM_PATHNAME always in effect has a lot of downside.
I'd expect that orderfile people have today will be broken and require tweaking if you switched WM_PATHNAME on.
Re: [PATCH 2/2] diff: document the pattern format for diff.orderFile
Quoted 18 lines · Junio C Hamano
Quoted 7 lines · Richard Hansen
Quoted 6 lines · Junio C Hamano
Quoted 3 lines · Richard Hansen
I was looking at the code to see how the two file formats differed and noticed that
match_order()doesn't set theWM_PATHNAMEflag when it callswildmatch(). That's unintentional (a bug), right?Quoted 6 lines
Quoted 3 lines
It has been that way from day one IIRC even before we introduced wildmatch()---IOW it may be intentional that the current code that uses
wildmatch()does not useWM_PATHNAME.You are the original author (
af5323e0272005-05-30). Do you remember what your intention was?Yes.
Quoted 7 lines
Back then we didn't even have
wildmatch(), and usedfnmatch()instead, so forcingFNM_PATHNAMEwould have meant that people wouldn't be able to say "foo*bar" to match "foo/other/bar"; with wildmatch, "foo**bar" lets you defeatWM_PATHNAMEso havingWM_PATHNAMEalways in effect is less of an issue, but withfnmatch(), havingFNM_PATHNAMEalways in effect has a lot of downside.
Ah, that makes sense.
Quoted 3 lines
I'd expect that orderfile people have today will be broken and require tweaking if you switched
WM_PATHNAMEon.
OK, so we don't want to turn on WM_PATHNAME unless we do it for a new major version.
I'll do another re-roll and document the non-WM_PATHNAME behavior. Perhaps I'll encourage users to prefer ** over * if they want to match slash (even though they are equivalent) so that migration is easier if we ever do turn on WM_PATHNAME.
-Richard
Re: [PATCH 1/2] diff: document behavior of relative diff.orderFile
In reply to Jeff KingQuoted 14 lines · Jeff King
Quoted 11 lines · Junio C Hamano
Richard Hansen <[email protected]> writes:
...Quoted 4 lines
I think so. (For bare repositories anyway; non-bare should be relative to
GIT_WORK_TREE.) Perhapsgit_config_pathname()itself should convert relative paths to absolute so that every pathname setting automatically works without changing any calling code.Yes, that was what I was alluding to. We might have to wait until major version boundary to do so, but I think that it is the sensible way forward in the longer term to convert relative to absolute in
git_config_pathname().
Quoted 8 lines
Yeah, I'd agree.
I'm undecided on whether it would need to happen at a major version bump. ...
So I dunno. I do hate to break even corner cases, but I'm having trouble imagining the scenario where somebody is actually using the current behavior in a useful way.
Thanks for a detailed analysis (I probably should have spelt them out when I said "we might have to" to save you the trouble).
Re: [PATCH 2/2] diff: document the pattern format for diff.orderFile
In reply to Richard HansenQuoted 8 lines · Richard Hansen
Quoted 7 lines
Back then we didn't even have
wildmatch(), and usedfnmatch()instead, so forcingFNM_PATHNAMEwould have meant that people wouldn't be able to say "foo*bar" to match "foo/other/bar"; with wildmatch, "foo**bar" lets you defeatWM_PATHNAMEso havingWM_PATHNAMEalways in effect is less of an issue, but withfnmatch(), havingFNM_PATHNAMEalways in effect has a lot of downside.
Quoted 7 lines
Ah, that makes sense.
Quoted 3 lines
I'd expect that orderfile people have today will be broken and require tweaking if you switched
WM_PATHNAMEon.OK, so we don't want to turn on
WM_PATHNAMEunless we do it for a new major version.
I do agree with you that if we were starting Git from scratch, or at least if we were adding diff.orderfile feature today, we would have used wildmatch(WM_PATHNAME) for this matching. We would also have used the same parser as used to read the exclude files (and when we see negative matching entries in the parsed result, either errored out or ignored them with warning). That kind of change unfortunately would require a major version bump, I am afraid.
v3 cover diff orderfile documentation improvements
In reply to Richard HansenChanges from v2:
* The orderfile feature doesn't set the WM_PATHNAME flag when it calls wildmatch(), so document the pattern format accordingly.
Richard Hansen (2):
diff: document behavior of relative diff.orderFile
diff: document the format of the -O (diff.orderFile) file
Documentation/diff-config.txt | 7 ++++--- Documentation/diff-options.txt | 34 ++++++++++++++++++++++++++++++++-- 2 files changed, 36 insertions(+), 5 deletions(-)
Signature · 1 line
2.11.0.483.g087da7b7c-goog
PATCH v3 1/2 diff: document behavior of relative diff.orderFile
Document that a relative pathname for diff.orderFile is interpreted as relative to the top-level work directory.
--- Documentation/diff-config.txt | 2 ++ 1 file changed, 2 insertions(+)
Documentation/diff-config.txt +2 -0
@@ -101,6 +101,8 @@ diff.noprefix:: diff.orderFile:: File indicating how to order files within a diff, using one shell glob pattern per line. + If `diff.orderFile` is a relative pathname, it is treated as + relative to the top of the work tree. Can be overridden by the '-O' option to linkgit:git-diff[1]. diff.renameLimit::
Signature · 1 line
2.11.0.483.g087da7b7c-goog
PATCH v3 2/2 diff: document the format of the -O (diff.orderFile) file
In reply to Richard Hansen--- Documentation/diff-config.txt | 5 ++--- Documentation/diff-options.txt | 34 ++++++++++++++++++++++++++++++++-- 2 files changed, 34 insertions(+), 5 deletions(-)
Documentation/diff-config.txt +2 -3
@@ -99,11 +99,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. + 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 work tree. - Can be overridden by the '-O' option to linkgit:git-diff[1]. diff.renameLimit:: The number of files to consider when performing the copy/rename
Documentation/diff-options.txt +32 -2
@@ -466,11 +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::
Signature · 1 line
2.11.0.483.g087da7b7c-goog