From 4159c5781303bb24d82be69b6a5de92d51d8d4f0 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Fri, 1 Jun 2007 05:10:30 -0400 Subject: Documentation: robustify asciidoc GIT_VERSION replacement Instead of using sed on the resulting file, we now have a git_version asciidoc attribute. This means that we don't pipe the output of asciidoc, which means we can detect build failures. Problem reported by Scott Lamb, solution suggested by Jonas Fonseca. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/Makefile | 6 ++---- Documentation/asciidoc.conf | 2 +- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index 3f92783d55..4064b38c44 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -112,8 +112,7 @@ clean: %.html : %.txt rm -f $@+ $@ $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \ - $(ASCIIDOC_EXTRA) -o - $< | \ - sed -e 's/@@GIT_VERSION@@/$(GIT_VERSION)/g' >$@+ + $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< mv $@+ $@ %.1 %.5 %.7 : %.xml @@ -122,8 +121,7 @@ clean: %.xml : %.txt rm -f $@+ $@ $(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \ - $(ASCIIDOC_EXTRA) -o - $< | \ - sed -e 's/@@GIT_VERSION@@/$(GIT_VERSION)/g' >$@+ + $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< mv $@+ $@ user-manual.xml: user-manual.txt user-manual.conf diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index fa7dc94845..60e15ba349 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -40,7 +40,7 @@ template::[header-declarations] {mantitle} {manvolnum} Git -@@GIT_VERSION@@ +{git_version} Git Manual -- cgit v1.2.1 From cedb8d5d33e6496cfc70493db841b3db886e8658 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Sat, 2 Jun 2007 10:08:54 -0700 Subject: 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. Signed-off-by: Josh Triplett Signed-off-by: Junio C Hamano --- 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 | 116 ++++++++++++++++++++++++++++++++++++ Documentation/repository-layout.txt | 3 +- Documentation/user-manual.txt | 12 ++-- 8 files changed, 145 insertions(+), 101 deletions(-) create mode 100644 Documentation/gitignore.txt diff --git a/Documentation/Makefile b/Documentation/Makefile index 4064b38c44..9cef4806d1 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -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)) diff --git a/Documentation/config.txt b/Documentation/config.txt index fdb71de9f6..7d9afe20f9 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -266,7 +266,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. diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 43e0d2266c..a78a9ff1b8 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -139,46 +139,24 @@ Exclude Patterns 'git-ls-files' can use a list of "exclude patterns" when traversing the directory tree and finding files to show when the -flags --others or --ignored are specified. +flags --others or --ignored are specified. gitlink:gitignore[5] +specifies the format of exclude patterns. -These exclude patterns come from these places: +These exclude patterns come from these places, in order: - 1. command line flag --exclude= specifies a single - pattern. + 1. The command line flag --exclude= specifies a + single pattern. Patterns are ordered in the same order + they appear in the command line. - 2. command line flag --exclude-from= specifies a list of - patterns stored in a file. + 2. The command line flag --exclude-from= specifies a + file containing a list of patterns. Patterns are ordered + in the same order they appear in the file. 3. command line flag --exclude-per-directory= specifies a name of the file in each directory 'git-ls-files' - examines, and if exists, its contents are used as an - additional list of patterns. - -An exclude pattern file used by (2) and (3) contains one pattern -per line. A line that starts with a '#' can be used as comment -for readability. - -There are three lists of patterns that are in effect at a given -time. They are built and ordered in the following way: - - * --exclude= from the command line; patterns are - ordered in the same order as they appear on the command line. - - * lines read from --exclude-from=; patterns are ordered - in the same order as they appear in the file. - - * When --exclude-per-directory= is specified, upon - entering a directory that has such a file, its contents are - appended at the end of the current "list of patterns". They - are popped off when leaving the directory. - -Each pattern in the pattern list specifies "a match pattern" and -optionally the fate; either a file that matches the pattern is -considered excluded or included. A filename is matched against -the patterns in the three lists; the --exclude-from list is -checked first, then the --exclude-per-directory list, and then -finally the --exclude list. The last match determines its fate. -If there is no match in the three lists, the fate is "included". + examines, normally `.gitignore`. Files in deeper + directories take precedence. Patterns are ordered in the + same order they appear in the files. A pattern specified on the command line with --exclude or read from the file specified with --exclude-from is relative to the @@ -186,58 +164,9 @@ top of the directory tree. A pattern read from a file specified by --exclude-per-directory is relative to the directory that the pattern file appears in. -An exclude pattern is of the following format: - - - an optional prefix '!' which means that the fate this pattern - specifies is "include", not the usual "exclude"; the - remainder of the pattern string is interpreted according to - the following rules. - - - if it does not contain a slash '/', it is a shell glob - pattern and used to match against the filename without - leading directories. - - - otherwise, it is a shell glob pattern, suitable for - consumption by fnmatch(3) with FNM_PATHNAME flag. I.e. a - slash in the pattern must match a slash in the pathname. - "Documentation/\*.html" matches "Documentation/git.html" but - not "ppc/ppc.html". As a natural exception, "/*.c" matches - "cat-file.c" but not "mozilla-sha1/sha1.c". - -An example: - --------------------------------------------------------------- - $ cat .git/info/exclude - # ignore objects and archives, anywhere in the tree. - *.[oa] - $ cat Documentation/.gitignore - # ignore generated html files, - *.html - # except foo.html which is maintained by hand - !foo.html - $ git-ls-files --ignored \ - --exclude='Documentation/*.[0-9]' \ - --exclude-from=.git/info/exclude \ - --exclude-per-directory=.gitignore --------------------------------------------------------------- - -Another example: - --------------------------------------------------------------- - $ cat .gitignore - vmlinux* - $ ls arch/foo/kernel/vm* - arch/foo/kernel/vmlinux.lds.S - $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore --------------------------------------------------------------- - -The second .gitignore keeps `arch/foo/kernel/vmlinux.lds.S` file -from getting ignored. - - See Also -------- -gitlink:git-read-tree[1] +gitlink:git-read-tree[1], gitlink:gitignore[5] Author @@ -246,7 +175,7 @@ Written by Linus Torvalds Documentation -------------- -Documentation by David Greaves, Junio C Hamano and the git-list . +Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list . GIT --- diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 019c8bef7a..acb57447a8 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -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 diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index d7015387b5..1fd1af102a 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -42,11 +42,9 @@ mean the same thing and the latter is kept for backward compatibility) and `color.status.` 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 ------ diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt new file mode 100644 index 0000000000..ea79d74b88 --- /dev/null +++ b/Documentation/gitignore.txt @@ -0,0 +1,116 @@ +gitignore(5) +============ + +NAME +---- +gitignore - Specifies intentionally untracked files to ignore + +SYNOPSIS +-------- +$GIT_DIR/info/exclude, .gitignore + +DESCRIPTION +----------- + +A `gitignore` file specifies intentionally untracked files that +git should ignore. Each line in a `gitignore` file specifies a +pattern. + +When deciding whether to ignore a path, git normally checks +`gitignore` patterns from multiple sources, with the following +order of precedence: + + * Patterns read from the file specified by the configuration + variable 'core.excludesfile'. + + * Patterns read from `$GIT_DIR/info/exclude`. + + * Patterns read from a `.gitignore` file in the same directory + as the path, or in any parent directory, ordered from the + deepest such file to a file in the root of the repository. + These patterns match relative to the location of the + `.gitignore` file. A project normally includes such + `.gitignore` files in its repository, containing patterns for + files generated as part of the project build. + +The underlying git plumbing tools, such as +gitlink:git-ls-files[1] and gitlink:git-read-tree[1], read +`gitignore` patterns specified by command-line options, or from +files specified by command-line options. Higher-level git +tools, such as gitlink:git-status[1] and gitlink:git-add[1], +use patterns from the sources specified above. + +Patterns have the following format: + + - A blank line matches no files, so it can serve as a separator + for readability. + + - A line starting with # serves as a comment. + + - An optional prefix '!' which negates the pattern; any + matching file excluded by a previous pattern will become + included again. + + - If the pattern does not contain a slash '/', git treats it as + a shell glob pattern and checks for a match against the + pathname without leading directories. + + - Otherwise, git treats the pattern as a shell glob suitable + for consumption by fnmatch(3) with the FNM_PATHNAME flag: + wildcards in the pattern will not match a / in the pathname. + For example, "Documentation/\*.html" matches + "Documentation/git.html" but not + "Documentation/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". + +An example: + +-------------------------------------------------------------- + $ git-status + [...] + # Untracked files: + [...] + # Documentation/foo.html + # Documentation/gitignore.html + # file.o + # lib.a + # src/internal.o + [...] + $ cat .git/info/exclude + # ignore objects and archives, anywhere in the tree. + *.[oa] + $ cat Documentation/.gitignore + # ignore generated html files, + *.html + # except foo.html which is maintained by hand + !foo.html + $ git-status + [...] + # Untracked files: + [...] + # Documentation/foo.html + [...] +-------------------------------------------------------------- + +Another example: + +-------------------------------------------------------------- + $ cat .gitignore + vmlinux* + $ ls arch/foo/kernel/vm* + arch/foo/kernel/vmlinux.lds.S + $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore +-------------------------------------------------------------- + +The second .gitignore prevents git from ignoring +`arch/foo/kernel/vmlinux.lds.S`. + +Documentation +------------- +Documentation by David Greaves, Junio C Hamano, Josh Triplett, +Frank Lichtenheld, and the git-list . + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt index 0459bd9ca1..15221b5320 100644 --- a/Documentation/repository-layout.txt +++ b/Documentation/repository-layout.txt @@ -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 diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 4fabb8e2a9..7eaafa80e9 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -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. -- cgit v1.2.1 From 996e2d6ea2626f55a59e70ac7305a02ce0171814 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kristian=20H=C3=B8gsberg?= Date: Fri, 1 Jun 2007 17:08:12 -0400 Subject: Use =20 when rfc2047 encoding spaces. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Encode ' ' using '=20' even though rfc2047 allows using '_' for readability. Unfortunately, many programs do not understand this and just leave the underscore in place. Using '=20' seems to work better. [jc: with adjustment to t3901] Signed-off-by: Kristian Høgsberg Signed-off-by: Junio C Hamano --- commit.c | 10 +++++++--- t/t3901-i18n-patch.sh | 10 +++++----- 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/commit.c b/commit.c index bee066fa32..5632e32685 100644 --- a/commit.c +++ b/commit.c @@ -511,12 +511,16 @@ static int add_rfc2047(char *buf, const char *line, int len, bp += i; for (i = 0; i < len; i++) { unsigned ch = line[i] & 0xFF; - if (is_rfc2047_special(ch)) { + /* + * We encode ' ' using '=20' even though rfc2047 + * allows using '_' for readability. Unfortunately, + * many programs do not understand this and just + * leave the underscore in place. + */ + if (is_rfc2047_special(ch) || ch == ' ') { sprintf(bp, "=%02X", ch); bp += 3; } - else if (ch == ' ') - *bp++ = '_'; else *bp++ = ch; } diff --git a/t/t3901-i18n-patch.sh b/t/t3901-i18n-patch.sh index a881797bc7..24bf0ee018 100755 --- a/t/t3901-i18n-patch.sh +++ b/t/t3901-i18n-patch.sh @@ -13,7 +13,7 @@ check_encoding () { while test "$i" -le $cnt do git format-patch --encoding=UTF-8 --stdout HEAD~$i..HEAD~$j | - grep "^From: =?UTF-8?q?=C3=81=C3=A9=C3=AD_=C3=B3=C3=BA?=" && + grep "^From: =?UTF-8?q?=C3=81=C3=A9=C3=AD=20=C3=B3=C3=BA?=" && git-cat-file commit HEAD~$j | case "$header" in 8859) @@ -73,9 +73,9 @@ test_expect_success 'format-patch output (ISO-8859-1)' ' git format-patch --stdout master..HEAD^ >out-l1 && git format-patch --stdout HEAD^ >out-l2 && grep "^Content-Type: text/plain; charset=ISO-8859-1" out-l1 && - grep "^From: =?ISO-8859-1?q?=C1=E9=ED_=F3=FA?=" out-l1 && + grep "^From: =?ISO-8859-1?q?=C1=E9=ED=20=F3=FA?=" out-l1 && grep "^Content-Type: text/plain; charset=ISO-8859-1" out-l2 && - grep "^From: =?ISO-8859-1?q?=C1=E9=ED_=F3=FA?=" out-l2 + grep "^From: =?ISO-8859-1?q?=C1=E9=ED=20=F3=FA?=" out-l2 ' test_expect_success 'format-patch output (UTF-8)' ' @@ -84,9 +84,9 @@ test_expect_success 'format-patch output (UTF-8)' ' git format-patch --stdout master..HEAD^ >out-u1 && git format-patch --stdout HEAD^ >out-u2 && grep "^Content-Type: text/plain; charset=UTF-8" out-u1 && - grep "^From: =?UTF-8?q?=C3=81=C3=A9=C3=AD_=C3=B3=C3=BA?=" out-u1 && + grep "^From: =?UTF-8?q?=C3=81=C3=A9=C3=AD=20=C3=B3=C3=BA?=" out-u1 && grep "^Content-Type: text/plain; charset=UTF-8" out-u2 && - grep "^From: =?UTF-8?q?=C3=81=C3=A9=C3=AD_=C3=B3=C3=BA?=" out-u2 + grep "^From: =?UTF-8?q?=C3=81=C3=A9=C3=AD=20=C3=B3=C3=BA?=" out-u2 ' test_expect_success 'rebase (U/U)' ' -- cgit v1.2.1