It is misleading to mention that <ref> that does not store is to
fetch the ref into FETCH_HEAD, because a refspec that does store is
also to fetch the LHS into FETCH_HEAD. It is doubly misleading to
list it as part of "short-cut". <ref> stands for a refspec that has
it on the LHS with a colon and an empty RHS, and that definition
should be given at the beginning of the entry where the format is
defined.
Tentatively remove this misleading description, which leaves the
`tag <tag>` as the only true short-hand, so move it at the beginning
of the entry.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The text made it sound as if the leading plus is the only thing that
is optional, and forgot that <lhs> is the same as <lhs>:, i.e. fetch
it and do not store anywhere.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Replace desription of old-style "Pull:" lines in remotes/
configuration with modern remote.*.fetch variables.
As this note applies only to "git pull", enable it only
in git-pull manual page.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
In old days before Git 1.5, it was customery for "git fetch" to use
the same local branch namespace to keep track of the remote-tracking
branches, and it was necessary to tell users not to check them out
and commit on them. Since everybody uses the separate remote layout
these days, there is no need to warn against the practice to check
out the right-hand side of <refspec> and build on it---the RHS is
typically not even a local branch.
Incidentally, this also kills one mention of "Pull:" line of
$GIT_DIR/remotes/* configuration, which is a lot less familiar to
new people than the more modern remote.*.fetch configuration
variable.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
While it is not *wrong* per-se to say that pulling a rewound/rebased
branch will lead to an unnecessary merge conflict, that is not what
the leading "+" sign to allow non-fast-forward update of remote-tracking
branch is at all.
Helped-by: Marc Branchaud <marcnarc@xiplink.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
When we run a regular "git fetch" without arguments, we
update the tracking refs according to the configured
refspec. However, when we run "git fetch origin master" (or
"git pull origin master"), we do not look at the configured
refspecs at all, and just update FETCH_HEAD.
We miss an opportunity to update "refs/remotes/origin/master"
(or whatever the user has configured). Some users find this
confusing, because they would want to do further comparisons
against the old state of the remote master, like:
$ git pull origin master
$ git log HEAD...origin/master
In the currnet code, they are comparing against whatever
commit happened to be in origin/master from the last time
they did a complete "git fetch". This patch will update a
ref from the RHS of a configured refspec whenever we happen
to be fetching its LHS. That makes the case above work.
The downside is that any users who really care about whether
and when their tracking branches are updated may be
surprised.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The documentation erroneously used the same wording for both fetch and
pull, stating that something will be merged even in git-fetch(1).
In addition, saying that "<ref> is equivalent to <ref>:" doesn't
really help anyone who still needs to read manpages. Clarify what is
actually going on.
Signed-off-by: Thomas Rast <trast@inf.ethz.ch>
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
In asciidoc 7, backticks like `foo` produced a typographic
effect, but did not otherwise affect the syntax. In asciidoc
8, backticks introduce an "inline literal" inside which markup
is not interpreted. To keep compatibility with existing
documents, asciidoc 8 has a "no-inline-literal" attribute to
keep the old behavior. We enabled this so that the
documentation could be built on either version.
It has been several years now, and asciidoc 7 is no longer
in wide use. We can now decide whether or not we want
inline literals on their own merits, which are:
1. The source is much easier to read when the literal
contains punctuation. You can use `master~1` instead
of `master{tilde}1`.
2. They are less error-prone. Because of point (1), we
tend to make mistakes and forget the extra layer of
quoting.
This patch removes the no-inline-literal attribute from the
Makefile and converts every use of backticks in the
documentation to an inline literal (they must be cleaned up,
or the example above would literally show "{tilde}" in the
output).
Problematic sites were found by grepping for '`.*[{\\]' and
examined and fixed manually. The results were then verified
by comparing the output of "html2text" on the set of
generated html pages. Doing so revealed that in addition to
making the source more readable, this patch fixes several
formatting bugs:
- HTML rendering used the ellipsis character instead of
literal "..." in code examples (like "git log A...B")
- some code examples used the right-arrow character
instead of '->' because they failed to quote
- api-config.txt did not quote tilde, and the resulting
HTML contained a bogus snippet like:
<tt><sub></tt> foo <tt></sub>bar</tt>
which caused some parsers to choke and omit whole
sections of the page.
- git-commit.txt confused ``foo`` (backticks inside a
literal) with ``foo'' (matched double-quotes)
- mentions of `A U Thor <author@example.com>` used to
erroneously auto-generate a mailto footnote for
author@example.com
- the description of --word-diff=plain incorrectly showed
the output as "[-removed-] and {added}", not "{+added+}".
- using "prime" notation like:
commit `C` and its replacement `C'`
confused asciidoc into thinking that everything between
the first backtick and the final apostrophe were meant
to be inside matched quotes
- asciidoc got confused by the escaping of some of our
asterisks. In particular,
`credential.\*` and `credential.<url>.\*`
properly escaped the asterisk in the first case, but
literally passed through the backslash in the second
case.
Signed-off-by: Jeff King <peff@peff.net>
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.
'git remote' is meant for managing remotes and 'git fetch' is meant
for actually fetching data from remote repositories. Therefore, it is
not logical that you must use 'git remote update' to fetch from
more than one repository at once.
Add the --all option to 'git fetch', to tell it to attempt to fetch
from all remotes. Also, if --all is not given, the <repository>
argument is allowed to be the name of a group, to allow fetching
from all repositories in the group.
Other options except -v and -q are silently ignored.
Signed-off-by: Björn Gustavsson <bgustavsson@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The refspec format description was a mix of regexp and BNF, making it
very difficult to read. The format was also wrong: it did not show
that each part of a refspec is optional in different situations.
Rather than having a confusing grammar, just present the format in
informal prose.
Signed-off-by: Anders Melchiorsen <mail@cup.kalibalik.dk>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
I see quite a few pages on k.org site, e.g.
http://www.kernel.org/pub/software/scm/git/docs/git-rerere.html
(scroll down to find "After this test merge")
are misformatted to lose teletype text '+' that is followed by a comma,
and turns the following paragraph all typeset in teletype.
This patch seems to fix the issue at the site (meaning, with the
particular vintage of asciidoc and docbook toolchain), without breaking
things with the version I have at my primary development machine, but
wider testing is very much appreciated.
After this patch,
git grep '`+`,' -- Documentation
should report noting.
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>
Alter the description of <repository> in OPTIONS section to
explicitly state that a 'remote name' is accepted.
Rewrite REMOTES section to more directly identify the
different kinds of remote-name permitted.
Signed-off-by: John J. Franey <jjfraney@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>
The sections on git urls and remotes files in the git-fetch,
git-pull, and git-push manpages seem long enough to be worth a
manpage section of their own.
Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
Signed-off-by: Junio C Hamano <junkio@cox.net>
The push and pull man pages include a bunch of shared text from
pull-fetch-param.txt. This simplifies maintenance somewhat, but
there's actually quite a bit of text that applies only to one or the
other.
So, separate out the push- and pull/fetch-specific text into
pull-fetch-param.txt and git-push.txt, then include the largest chunk
of common stuff (the description of protocols and url's) from
urls.txt. That cuts some irrelevant stuff from the man pages without
making us duplicate too much.
Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
Signed-off-by: Junio C Hamano <junkio@cox.net>
Dropped a fair amount of reundant code in favour of the library code
in path.c
Added option --strict-paths with documentation, with backwards
compatibility for whitelist entries with symlinks.
Everything that worked earlier still works insofar as I have
remembered testing it.
Signed-off-by: Andreas Ericsson <ae@op5.se>
Signed-off-by: Junio C Hamano <junkio@cox.net>
You could also spell it ssh://host:/path/to/repo (or git+ssh,
ssh+git), but without method:// is shorter to type, so mention
only that one in the short and sweet list.
Noticed by Pasky.
Signed-off-by: Junio C Hamano <junkio@cox.net>
Josef Weidendorfer points out that git-clone documentation does not
mention the initial copying of remote branch heads into corresponding
local branches. Also clarify the purpose of the ref mappings description
in the "remotes" file and recommended workflow.
Signed-off-by: Junio C Hamano <junkio@cox.net>
We do not accept multiple <refspecs> on one Pull:/Push: line
right now (we could lift this tentative workaround for the
broken refnames), but we have always accepted multiple such
lines, so use that form in the examples and discussion.
Also explicitly mention that Octopus is made only with an
explicit command line request and never from Pull: lines.
Add a couple of cross references.
Signed-off-by: Junio C Hamano <junkio@cox.net>
Clarified and added notes for pull/push refspecs.
Converted to back-ticks for literal text examples.
[jc: Also fixed git-pull description that still talked about its
calling git-resolve or git-octopus (we do not anymore; instead
we just call git-merge). BTW, I am reasonably impressed by how
well "git-am -3" applied this patch, which had some conflicts
because I've updated the documentation somewhat.]
Signed-off-by: Jon Loeliger <jdl@freescale.com>
Signed-off-by: Junio C Hamano <junkio@cox.net>
The documentation was lazily sharing the argument description across these
commands.
Lazy may be a way of life, but that does not justify confusing others ;-).
Signed-off-by: Junio C Hamano <junkio@cox.net>
The fixes focuses on improving the HTML output. Most noteworthy:
- Fix the Makefile to also make various *.html files depend on
included files.
- Consistently use 'NOTE: ...' instead of '[ ... ]' for additional
info.
- Fix ending '::' for description lists in OPTION section etc.
- Fix paragraphs in description lists ending up as preformated text.
- Always use listingblocks (preformatted text wrapped in lines with -----)
for examples that span empty lines, so they are put in only one HTML
block.
- Use '1.' instead of '(1)' for numbered lists.
- Fix linking to other GIT docs.
- git-rev-list.txt: put option descriptions in an OPTION section.
Signed-off-by: Jonas Fonseca <fonseca@diku.dk>
Signed-off-by: Junio C Hamano <junkio@cox.net>
Describe short-hand for remote repository used in fetch/pull.
Signed-off-by: Junio C Hamano <junkio@cox.net>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Marc Branchaud