Create a new manpage for the gitignore format, and reference it elsewhere
PATCH 1/1 Create a new manpage for the gitignore format, and reference it elsewhere
Only git-ls-files(1) describes the gitignore format in detail, and it does so with reference to git-ls-files options. Most users don't use the plumbing command git-ls-files directly, and shouldn't have to look in its manpage for information on the gitignore format.
Create a new manpage gitignore(5) (Documentation/gitignore.txt), and factor out the gitignore documentation into that file, changing it to refer to .gitignore and $GIT_DIR/info/exclude as used by porcelain commands. Reference gitignore(5) from other relevant manpages and documentation. Remove now-redundant information on exclude patterns from git-ls-files(1), leaving only information on how git-ls-files options specify exclude patterns and what precedence they have.
--- Documentation/Makefile | 2 +- Documentation/config.txt | 3 +- Documentation/git-ls-files.txt | 99 +++++----------------------------- Documentation/git-read-tree.txt | 3 +- Documentation/git-status.txt | 8 +-- Documentation/gitignore.txt | 100 +++++++++++++++++++++++++++++++++++ Documentation/repository-layout.txt | 3 +- Documentation/user-manual.txt | 12 ++-- 8 files changed, 129 insertions(+), 101 deletions(-) create mode 100644 Documentation/gitignore.txt
Documentation/Makefile +1 -1
@@ -2,7 +2,7 @@ MAN1_TXT= \ $(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \ $(wildcard git-*.txt)) \ gitk.txt -MAN5_TXT=gitattributes.txt +MAN5_TXT=gitattributes.txt gitignore.txt MAN7_TXT=git.txt DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))
Documentation/config.txt +2 -1
@@ -259,7 +259,8 @@ Common unit suffixes of 'k', 'm', or 'g' are supported. core.excludeFile:: In addition to '.gitignore' (per-directory) and '.git/info/exclude', git looks into this file for patterns - of files which are not meant to be tracked. + of files which are not meant to be tracked. See + gitlink:gitignore[5]. alias.*:: Command aliases for the gitlink:git[1] command wrapper - e.g.
Documentation/git-ls-files.txt +14 -85
125 lines not on this page · raw message
Documentation/git-read-tree.txt +2 -1
@@ -341,7 +341,8 @@ have finished your work-in-progress), attempt the merge again. See Also -------- -gitlink:git-write-tree[1]; gitlink:git-ls-files[1] +gitlink:git-write-tree[1]; gitlink:git-ls-files[1]; +gitlink:gitignore[5] Author
Documentation/git-status.txt +3 -5
@@ -42,11 +42,9 @@ mean the same thing and the latter is kept for backward compatibility) and `color.status.<slot>` configuration variables to colorize its output. -As for gitlink:git-add[1], the configuration variable -'core.excludesfile' can indicate a path to a file containing patterns -of file names to exclude, in addition to patterns given in -'info/exclude' and '.gitignore'. - +See Also +-------- +gitlink:gitignore[5] Author ------
Documentation/gitignore.txt new file +100 -0
100 lines not on this page · raw message
Documentation/repository-layout.txt +1 -2
@@ -155,8 +155,7 @@ info/exclude:: exclude pattern list. `.gitignore` is the per-directory ignore file. `git status`, `git add`, `git rm` and `git clean` look at it but the core git commands do not look - at it. See also: gitlink:git-ls-files[1] `--exclude-from` - and `--exclude-per-directory`. + at it. See also: gitlink:gitignore[5]. remotes:: Stores shorthands to be used to give URL and default
Documentation/user-manual.txt +6 -6
@@ -1103,12 +1103,12 @@ showing up in the output of "`git status`", etc. Git therefore provides "exclude patterns" for telling git which files to actively ignore. Exclude patterns are thoroughly explained in the -"Exclude Patterns" section of the gitlink:git-ls-files[1] manual page, -but the heart of the concept is simply a list of files which git should -ignore. Entries in the list may contain globs to specify multiple files, -or may be prefixed by "`!`" to explicitly include (un-ignore) a previously -excluded (ignored) file (i.e. later exclude patterns override earlier ones). -The following example should illustrate such patterns: +gitlink:gitignore[5] manual page, but the heart of the concept is simply +a list of files which git should ignore. Entries in the list may contain +globs to specify multiple files, or may be prefixed by "`!`" to +explicitly include (un-ignore) a previously excluded (ignored) file +(i.e. later exclude patterns override earlier ones). The following +example should illustrate such patterns: ------------------------------------------------- # Lines starting with '#' are considered comments.
Signature · 1 line
1.5.2
Cool :)
Some remarks below.
Quoted 2 lines · Josh Triplett
Signed-off-by Josh Triplett <[email protected]>Signed-off-by Josh Triplett <[email protected]>
:) (Wanted to make some funny remark, but its too late here to be funny in a foreign language...)
Documentation/git-ls-files.txt Written by Linus Torvalds <[email protected]> · line 178
Quoted 4 lines
Documentation
--------------Documentation/git-ls-files.txt +1
-1-Documentation by David Greaves, Junio C Hamano and the git-list <[email protected]>. +Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list <[email protected]>.
No offence, but adding your name here for removing content? ;)
Documentation/gitignore.txt line 39
Quoted 4 lines
Documentation/gitignore.txt new file +4
-0+Some git plumbing tools, such as git-ls-files(1) and +git-read-tree(1), read `gitignore` patterns specified by +command-line options, or from files specified by command-line +options.
Missing gitlink:
Also I don't like the paragraph. It should probably mention that these programs actually implement the behaviour described, that they aren't hardcoded to the mentioned filenames and that all git porcelain just happens to call them with them.
But, as said, too late here for proper English ;)
Documentation/gitignore.txt line 46
Quoted 6 lines
Documentation/gitignore.txt new file +6
-0+Patterns have the following format: + + - A blank line matches no files, so it can serve as a separator + for readability. + + - A line starting with #
Is here missing something?
Documentation/gitignore.txt line 62
Quoted 7 lines
+ - Otherwise, git treats the pattern as a shell glob suitable
Documentation/gitignore.txt new file +6
-0+ for consumption by fnmatch(3) with the FNM_PATHNAME flag: any + slash in the pattern must match a slash in the pathname. For + example, "Documentation/\*.html" matches + "Documentation/git.html" but not "ppc/ppc.html". A leading + slash matches the beginning of the pathname; for example, + "/*.c" matches "cat-file.c" but not "mozilla-sha1/sha1.c".
I realise this is copy&paste but shouldn't that read:
"Documentation/\*.html" matches "Documentation/git.html" but not "Documentation/ppc/ppc.html"
?
Documentation/gitignore.txt line 96
Quoted 3 lines
Documentation/gitignore.txt new file +3
-0+Documentation +------------- +Documentation by Josh Triplett.
No offence again, but given the amount of copy&paste, maybe the names from git-ls-files should also be added here.
Gruesse,
Signature · 2 lines
Frank Lichtenheld <[email protected]> www: http://www.djpig.de/
Quoted 6 lines · Frank Lichtenheld
Quoted 2 lines · Josh Triplett
Signed-off-by Josh Triplett <[email protected]>Signed-off-by Josh Triplett <[email protected]>:) (Wanted to make some funny remark, but its too late here to be funny in a foreign language...)
Argh. git-commit -s --amend signed a second time. Sorry I missed this.
Quoted 6 lines
Documentation/git-ls-files.txt Written by Linus Torvalds <[email protected]> · line 178
Quoted 4 lines
Documentation
--------------Documentation/git-ls-files.txt +1
-1-Documentation by David Greaves, Junio C Hamano and the git-list <[email protected]>. +Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list <[email protected]>.No offence, but adding your name here for removing content? ;)
I intentionally avoided adding my name to the pages in which I only removed content, or only added a reference to gitignore(5). In the case of git-ls-files, I rewrote some of the material. However, I don't care that strongly about the credit.
Quoted 6 lines
Documentation/gitignore.txt line 39
Quoted 4 lines
Documentation/gitignore.txt new file +4
-0+Some git plumbing tools, such as git-ls-files(1) and +git-read-tree(1), read `gitignore` patterns specified by +command-line options, or from files specified by command-line +options.Missing gitlink:
Ah, good point.
Quoted 4 lines
Also I don't like the paragraph. It should probably mention that these programs actually implement the behaviour described, that they aren't hardcoded to the mentioned filenames and that all git porcelain just happens to call them with them.
That seems like an implementation detail, only relevant to users of git-ls-files and git-read-tree.
Quoted 8 lines
Documentation/gitignore.txt line 46
Quoted 6 lines
Documentation/gitignore.txt new file +6
-0+Patterns have the following format: + + - A blank line matches no files, so it can serve as a separator + for readability. + + - A line starting with #Is here missing something?
Oops. Yes, this should have said:
- A line starting with # serves as a comment.
Quoted 8 lines
Documentation/gitignore.txt line 62
Quoted 7 lines
+ - Otherwise, git treats the pattern as a shell glob suitable
Documentation/gitignore.txt new file +6
-0+ for consumption by fnmatch(3) with the FNM_PATHNAME flag: any + slash in the pattern must match a slash in the pathname. For + example, "Documentation/\*.html" matches + "Documentation/git.html" but not "ppc/ppc.html". A leading + slash matches the beginning of the pathname; for example, + "/*.c" matches "cat-file.c" but not "mozilla-sha1/sha1.c".
Quoted 4 lines
I realise this is copy&paste but shouldn't that read:
"Documentation/\*.html" matches "Documentation/git.html" but not "Documentation/ppc/ppc.html"
?
I don't know. Neither file seems to exist in current Git.
Quoted 6 lines
Documentation/gitignore.txt line 96
Quoted 3 lines
Documentation/gitignore.txt new file +3
-0+Documentation +------------- +Documentation by Josh Triplett.No offence again, but given the amount of copy&paste, maybe the names from git-ls-files should also be added here.
Entirely correct; I don't know why I missed that, as I had intended to copy those names. My apologies.
Expect an updated patch shortly, to fix the issues you pointed out.
- Josh Triplett
Quoted 10 lines · Josh Triplett
Quoted 9 lines · Frank Lichtenheld
Quoted 7 lines · Josh Triplett
+ - Otherwise, git treats the pattern as a shell glob suitable
Documentation/gitignore.txt new file +6
-0+ for consumption by fnmatch(3) with the FNM_PATHNAME flag: any + slash in the pattern must match a slash in the pathname. For + example, "Documentation/\*.html" matches + "Documentation/git.html" but not "ppc/ppc.html". A leading + slash matches the beginning of the pathname; for example, + "/*.c" matches "cat-file.c" but not "mozilla-sha1/sha1.c".
Quoted 6 lines
Quoted 4 lines
I realise this is copy&paste but shouldn't that read:
"Documentation/\*.html" matches "Documentation/git.html" but not "Documentation/ppc/ppc.html"
?I don't know. Neither file seems to exist in current Git.
The point I was trying to make is that "Documentation/*.html" _of course_ doesn't match ppc/ppc.html. What we try to tell the user here is that * doesn't match /
So I think it should definetly read Documentation/ppc/ppc.html FWIW, I find the sentence
"any slash in the pattern must match a slash in the pathname" very confusing too. The sentence in fnmatch(3) is much more precise:
"match a slash in string only with a slash in pattern and not by an asterisk (*) or a question mark (?) metacharacter, nor by a bracket expression ([]) containing a slash"
Anyway, if you prefer (and if it is okay with Junio) I can send a patch of my own for this single issue to not hinder the commit of your big patch as the issue is equally present in the old and the new text.
Gruesse,
Signature · 2 lines
Frank Lichtenheld <[email protected]> www: http://www.djpig.de/
Quoted 14 lines · Frank Lichtenheld
Quoted 13 lines · Josh Triplett
Quoted 12 lines · Frank Lichtenheld
Documentation/gitignore.txt line 62
Quoted 7 lines · Josh Triplett
+ - Otherwise, git treats the pattern as a shell glob suitable
Documentation/gitignore.txt new file +6
-0+ for consumption by fnmatch(3) with the FNM_PATHNAME flag: any + slash in the pattern must match a slash in the pathname. For + example, "Documentation/\*.html" matches + "Documentation/git.html" but not "ppc/ppc.html". A leading + slash matches the beginning of the pathname; for example, + "/*.c" matches "cat-file.c" but not "mozilla-sha1/sha1.c".I realise this is copy&paste but shouldn't that read:
"Documentation/\*.html" matches "Documentation/git.html" but not "Documentation/ppc/ppc.html"
?
Quoted 6 lines
Quoted 1 line
I don't know. Neither file seems to exist in current Git.
The point I was trying to make is that "
Documentation/*.html"_ofcourse_doesn't match ppc/ppc.html. What we try to tell the user here is that * doesn't match /
So I think it should definetly readDocumentation/ppc/ppc.html
Ah, I understand your point now.
Quoted 6 lines
FWIW, I find the sentence
"any slash in the pattern must match a slash in the pathname" very confusing too. The sentence in fnmatch(3) is much more precise:
"match a slash in string only with a slash in pattern and not by an asterisk (*) or a question mark (?) metacharacter, nor by a bracket expression ([]) containing a slash"
I like that better as well.
Quoted 4 lines
Anyway, if you prefer (and if it is okay with Junio) I can send a patch of my own for this single issue to not hinder the commit of your big patch as the issue is equally present in the old and the new text.
Now that I understand the issue you raised, I can easily fix it and send a revised patch. Expect one momentarily.
- Josh Triplett
Quoted 2 lines · Josh Triplett
Now that I understand the issue you raised, I can easily fix it and send a revised patch. Expect one momentarily.
Thanks both. Yes the original description showed my incompetence in wording.