It is an implementation detail that a new tag is created by adding a
file in the .git/refs/tags directory. The only thing the user needs
to know is that a "git tag" creates a ref in the refs/tags namespace,
and without "-f", it does not overwrite an existing tag.
Inspired by a report from 乙酸鋰 <ch3cooli@gmail.com>; I think I
caught all the existing mention in Documentation/ directory in the
tip of 1.7.9.X maintenance track, but we may have added new ones
since then.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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.
"remote branch" is a branch hosted in a remote repository, while
"remote-tracking branch" is a copy of such branch, hosted locally.
The distinction is subtle when the copy is up-to-date, but rather
fundamental to understand what "git fetch" and "git push" do.
This patch should fix all incorrect usages in Documentation/ directory.
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
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.
Introduced in 492cf3f (More precise description of 'git describe --abbrev', 2009-10-29)
Signed-off-by: Gisle Aas <gisle@aas.no>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Also adds a note about why the output in the examples might give
different output today.
Signed-off-by: Gisle Aas <gisle@aas.no>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
With the --dirty option, git describe works on HEAD but append s"-dirty"
iff the contents of the work tree differs from HEAD. E.g.
$ git describe --dirty
v1.6.5-15-gc274db7
$ echo >> Makefile
$ git describe --dirty
v1.6.5-15-gc274db7-dirty
The --dirty option can also be used to specify what is appended, instead
of the default string "-dirty".
$ git describe --dirty=.mod
v1.6.5-15-gc274db7.mod
Many build scripts use `git describe` to produce a version number based on
the description of HEAD (on which the work tree is based) + saying that if
the build contains uncommitted changes. This patch helps the writing of
such scripts since `git describe --dirty` does directly the intended thing.
Three possiblities were considered while discussing this new feature:
1. Describe the work tree by default and describe HEAD only if "HEAD" is
explicitly specified
Pro: does the right thing by default (both for users and for scripts)
Pro: other git commands that works on the work tree by default
Con: breaks existing scripts used by the Linux kernel and other projects
2. Use --worktree instead of --dirty
Pro: does what it says: "git describe --worktree" describes the work tree
Con: other commands do not require a --worktree option when working
on the work tree (it often is the default mode for them)
Con: unusable with an optional value: "git describe --worktree=.mod"
is quite unintuitive.
3. Use --dirty as in this patch
Pro: makes sense to specify an optional value (what the dirty mark is)
Pro: does not have any of the big cons of previous alternatives
* does not break scripts
* is not inconsistent with other git commands
This patch takes the third approach.
Signed-off-by: Jean Privat <jean@pryen.org>
Acked-by: Shawn O. Pearce <spearce@spearce.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The documentation for git-describe says the default abbreviation is 8
hexadecimal digits while cache.c clearly shows DEFAULT_ABBREV set to 7.
This patch corrects the documentation.
Signed-off-by: Boyd Stephen Smith Jr <bss@iguanasuicide.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Some instances replaced by "handful of", others use
the word "few", a couple get a slight rewording.
Signed-off-by: Jon Loeliger <jdl@freescale.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
If the caller supplies --tags they want the lightweight, unannotated
tags to be searched for a match. If a lightweight tag is closer
in the history, it should be matched, even if an annotated tag is
reachable further back in the commit chain.
The same applies with --all when matching any other type of ref.
Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
Acked-By: Uwe Kleine-König <ukleinek@strlen.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
When the SYNOPSIS says e.g. "<path>...", it is nice if the DESCRIPTION
also mentions "<path>..." and says the specified "paths" (note plural)
are used for $whatever. This fixes the obvious mismatches.
Signed-off-by: Abhijit Menon-Sen <ams@toroid.org>
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>
This is useful when you want to see parts of the commit object name
in "describe" output, even when the commit in question happens to be
a tagged version. Instead of just emitting the tag name, it will
describe such a commit as v1.2-0-deadbeef (0th commit since tag v1.2
that points at object deadbeef....).
Signed-off-by: Santi Béjar <sbejar@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Sometimes scripts want (or need) the annotated tag name that exactly
matches a specific commit, or no tag at all. In such cases it can be
difficult to determine if the output of `git describe $commit` is a
real tag name or a tag+abbreviated commit. A common idiom is to run
git-describe twice:
if test $(git describe $commit) = $(git describe --abbrev=0 $commit)
...
but this is a huge waste of time if the caller is just going to pick a
different method to describe $commit or abort because it is not exactly
an annotated tag.
Setting the maximum number of candidates to 0 allows the caller to ask
for only a tag that directly points at the supplied commit, or to have
git-describe abort if no such item exists.
Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
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>
This uses "git-apply --whitespace=strip" to fix whitespace errors that have
crept in to our source files over time. There are a few files that need
to have trailing whitespaces (most notably, test vectors). The results
still passes the test, and build result in Documentation/ area is unchanged.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Often users want to know not which tagged version a commit came
after, but which tagged version a commit is contained within.
This latter task is the job of git-name-rev, but most users are
looking to git-describe to do the job.
Junio suggested we make `git describe --contains` run the correct
tool, `git name-rev`, and that's exactly what we do here. The output
of name-rev was adjusted slightly through the new --name-only option,
allowing describe to execv into name-rev and maintain its current
output format.
Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
Signed-off-by: Junio C Hamano <junkio@cox.net>
My prior version of git-describe ran very slowly on even reasonably
sized projects like git.git and linux.git as it tended to identify
a large number of possible tags and then needed to generate the
revision list for each of those tags to sort them and select the
best tag to describe the input commit.
All we really need is the number of commits in the input revision
which are not in the tag. We can generate these counts during
the revision walking and tag matching loop by assigning a color to
each tag and coloring the commits as we walk them. This limits us
to identifying no more than 26 possible tags, as there is limited
space available within the flags field of struct commit.
The limitation of 26 possible tags is hopefully not going to be a
problem in real usage, as most projects won't create 26 maintenance
releases and merge them back into a development trunk after the
development trunk was tagged with a release candidate tag. If that
does occur git-describe will start to revert to its old behavior of
using the newer maintenance release tag to describe the development
trunk, rather than the development trunk's own tag. The suggested
workaround would be to retag the development trunk's tip.
However since even 26 possible tags can take a while to generate a
description for on some projects I'm defaulting the limit to 10 but
offering the user --candidates to increase the number of possible
matches if they need a more accurate result. I specifically chose
10 for the default as it seems unlikely projects will have more
than 10 maintenance releases merged into a development trunk before
retagging the development trunk, and it seems to perform about the
same on linux.git as v1.4.4.4 git-describe.
A large amount of debugging information was also added during
the development of this change, so I've left it in to be toggled
on with --debug. It may be useful to the end user to help them
understand why git-describe took one particular tag over another.
Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
Signed-off-by: Junio C Hamano <junkio@cox.net>
All should be clear enough, except perhaps committish / commitish.
I just kept the more-used one within the current docs.
[jc: with rephrasing of check-ref-format description later discussed
on the list]
Signed-off-by: Francis Daly <francis@daoine.org>
Signed-off-by: Junio C Hamano <junkio@cox.net>
Junio C Hamano