The point of these sections is generally to:
1. Give credit where it is due.
2. Give the reader an idea of where to ask questions or
file bug reports.
But they don't do a good job of either case. For (1), they
are out of date and incomplete. A much more accurate answer
can be gotten through shortlog or blame. For (2), the
correct contact point is generally git@vger, and even if you
wanted to cc the contact point, the out-of-date and
incomplete fields mean you're likely sending to somebody
useless.
So let's drop the fields entirely from all manpages except
git(1) itself. We already point people to the mailing list
for bug reports there, and we can update the Authors section
to give credit to the major contributors and point to
shortlog and blame for more information.
Each page has a "This is part of git" footer, so people can
follow that to the main git manpage.
A frequently asked question on #git is how to stop tracking a file
that is mistakenly tracked by git. A frequently attempted strategy is
to add such files to .gitignore.
Thus one might imagine that the gitignore documentation could be a
good entry point for 'git rm' documentation. Add some
cross-references in this vein.
While at it, move a reference to update-index --assume-unchanged from
the DESCRIPTION to lower down on the page. This way, the methodical
reader can benefit from first learning what excludes files do, then
how they relate to other git facilities.
Based-on-patch-by: Sitaram Chamarty <sitaram@atc.tcs.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
A learner-by-example might want to look at the examples section first.
Help her out by supplying some section headings: PATTERN FORMAT for
the format of lines in an excludes file and EXAMPLES for the two
examples.
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
An asterisk in "Documentation/*.txt" quoted with \ to avoid bold text
is being output as \* because asciidoc does not consider it a
candidate for escaping (there is no matching * to pair it with).
So the manual looks like it is saying that one should write
"Documentation/\*.txt" in the .gitignore file.
Reported-by: Frédéric Brière <fbriere@fbriere.net>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Patterns containing a / are implicitly anchored to the directory
containing the relevant .gitignore file.
Patterns not containing a / are textual matches against the path
name relative to the directory containing .gitignore.
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The documentation was quite inconsistent when spelling 'git cmd' if it
only refers to the program, not to some specific invocation syntax:
both 'git-cmd' and 'git cmd' spellings exist.
The current trend goes towards dashless forms, and there is precedent
in 647ac70 (git-svn.txt: stop using dash-form of commands.,
2009-07-07) to actively eliminate the dashed variants.
Replace 'git-cmd' with 'git cmd' throughout, except where git-shell,
git-cvsserver, git-upload-pack, git-receive-pack, and
git-upload-archive are concerned, because those really live in the
$PATH.
Use the term "toplevel of the work tree" in gitattributes.txt and
gitignore.txt to define the limits of the search for those files.
Signed-off-by: Jason Merrill <jason@redhat.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This patch explains more carefully that `.gitignore` concerns only
untracked files and refers the reader to
git update-index --assume-unchanged
in the need of ignoring uncommitted changes in already tracked files.
The description of this option is lifted to a more "porcelainish"
level and explains the caveats of this usecase.
Whether feasible or not, I believe adding this functionality to
the porcelain is out of the scope of this patch. (And I personally
think that referring to the plumbing in the case of such a special
usage is fine.)
This is currently probably one of the top FAQs at #git and the
--assume-unchanged switch is not widely known; gitignore(5) is the first
place where people are likely to look for it.
Signed-off-by: Petr Baudis <pasky@suse.cz>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The names of git commands are not meant to be entered at the
commandline; they are just names. So we render them in italics,
as is usual for command names in manpages.
Using
doit () {
perl -e 'for (<>) { s/\`(git-[^\`.]*)\`/'\''\1'\''/g; print }'
}
for i in git*.txt config.txt diff*.txt blame*.txt fetch*.txt i18n.txt \
merge*.txt pretty*.txt pull*.txt rev*.txt urls*.txt
do
doit <"$i" >"$i+" && mv "$i+" "$i"
done
git diff
.
Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Following what appears to be the predominant style, format
names of commands and commandlines both as `teletype text`.
While we're at it, add articles ("a" and "the") in some
places, italicize the name of the command in the manual page
synopsis line, and add a comma or two where it seems appropriate.
Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Since the git-* commands are not installed in $(bindir), using
"git-command <parameters>" in examples in the documentation is
not a good idea. On the other hand, it is nice to be able to
refer to each command using one hyphenated word. (There is no
escaping it, anyway: man page names cannot have spaces in them.)
This patch retains the dash in naming an operation, command,
program, process, or action. Complete command lines that can
be entered at a shell (i.e., without options omitted) are
made to use the dashless form.
The changes consist only of replacing some spaces with hyphens
and vice versa. After a "s/ /-/g", the unpatched and patched
versions are identical.
Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
As the "git" man page describes the "git" command at the end-user
level, it seems better to move it to man section 1.
Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* maint:
Update draft release notes for 1.5.4.5
Documentation: clarify use of .git{ignore,attributes} versus .git/info/*
t/t3800-mktag.sh: use test_must_fail rather than '!'
Conflicts:
t/t3800-mktag.sh
gitignore patterns can be read from three different
files, while gitattributes can come from two files. Let's
provide some hints to the user about the differences and how
they are typically used.
Suggested by Toby Corkindale, but gratuitously reworded by Jeff King.
Signed-off-by: Toby Corkindale <toby.corkindale@rea-group.com>
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
A pattern "foo/" in the exclude list did not match directory
"foo", but a pattern "foo" did. This attempts to extend the
exclude mechanism so that it would while not matching a regular
file or a symbolic link "foo". In order to differentiate a
directory and non directory, this passes down the type of path
being checked to excluded() function.
A downside is that the recursive directory walk may need to run
lstat(2) more often on systems whose "struct dirent" do not give
the type of the entry; earlier it did not have to do so for an
excluded path, but we now need to figure out if a path is a
directory before deciding to exclude it. This is especially bad
because an idea similar to the earlier CE_UPTODATE optimization
to reduce number of lstat(2) calls would by definition not apply
to the codepaths involved, as (1) directories will not be
registered in the index, and (2) excluded paths will not be in
the index anyway.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock
Asciidoc configuration:
@@ -149,7 +153,10 @@
# Inline macros.
# Backslash prefix required for escape processing.
# (?s) re flag for line spanning.
-(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])=
+
+# Explicit so they can be nested.
+(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])=
+
# Anchor: [[[id]]]. Bibliographic anchor.
(?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3
# Anchor: [[id,xreflabel]]
This default regex now matches explicit values, and unfortunately in this
case gitlink was being matched by just 'link', causing the wrong inline
macro template to be applied. By renaming the macro, we can avoid being
matched by the wrong regex.
Signed-off-by: Dan McGee <dpmcgee@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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 <josh@freedesktop.org>
Signed-off-by: Junio C Hamano <junkio@cox.net>
