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>
Text between two '*' is emphasized in AsciiDoc and makes explanations in
rev-list-options.txt on glob-related options very confusing, as the
rendered text would be missing two asterisks and the text between them
would be emphasized instead.
Use '{asterisk}' where needed to make them show up as asterisks in the
rendered text.
Signed-off-by: Carlos Martín Nieto <cmn@elego.de>
Acked-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* maint:
doc/fast-import: clarify notemodify command
Documentation: minor grammatical fix in rev-list-options.txt
Documentation: git-filter-branch honors replacement refs
remote-curl: Add a format check to parsing of info/refs
git-config: Remove extra whitespaces
AsciiDoc versions since 5.0.6 treat a double-dash surrounded by spaces
(outside of verbatim environments) as a request to insert an em dash.
Such versions also treat the three-character sequence "\--", when not
followed by another dash, as a request to insert two literal minus
signs. Thus from time to time there have been patches to add
backslashes to AsciiDoc markup to escape double-dashes that are meant
to be represent '--' characters used literally on the command line;
see v1.4.0-rc1~174, Fix up docs where "--" isn't displayed correctly,
2006-05-05, for example.
AsciiDoc 6.0.3 (2005-04-20) made life harder by also treating
double-dashes without surrounding whitespace as markup for an em dash,
though only when formatting for backends other than the manpages
(e.g., HTML). Many pages needed to be changed to use a backslash
before the "--" in names of command-line flags like "--add" (see
v0.99.6~37, Update tutorial, 2005-08-30).
AsciiDoc 8.3.0 (2008-11-29) refined the em-dash rule to avoid that
requirement. Double-dashes without surrounding spaces are not
rendered as em dashes any more unless bordered on both sides by
alphanumeric characters. The unescaped markup for option names (e.g.,
"--add") works fine, and many instances of this style have leaked into
Documentation/; git's HTML documentation contains many spurious em
dashes when formatted by an older toolchain. (This patch will not
change that.)
The upshot: "--" as an isolated word and in phrases like "git
web--browse" must be escaped if it is not to be rendered as an em dash
by current asciidoc. Use "\--" to avoid such misformatting in
sentences in which "--" represents a literal double-minus command line
argument that separates options and revs from pathspecs, and use
"{litdd}" in cases where the double-dash is embedded in the command
name. The latter is just for consistency with v1.7.3-rc0~13^2 (Work
around em-dash handling in newer AsciiDoc, 2010-08-23).
List of lines to fix found by grepping manpages for "(em".
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Improved-by: Junio C Hamano <gitster@pobox.com>
Improved-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Instead of barfing, simply ignore bad object names seen in the
input. This is useful when reading from "git notes list" output
that may refer to objects that have already been garbage collected.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
When --count is used with --cherry-mark, omit the patch equivalent
commits from the count for left and right commits and print the count of
equivalent commits separately.
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Earlier f98fd43 (git-log.txt,rev-list-options.txt: put option blocks in
proper order, 2011-03-08) moved the text around in the documentation for
options in the rev-list family of commands such as "log". Consequently,
the description of the --cherry-pick option appears way above the
description of the --left-right option now.
But the description of the --cherry-pick option still refers to the
example for the --left-right option, like this:
... with --left-right, like the example ABOVE in the description of
that option.
Rephrase it to clarify that we are making a forward reference.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* mg/rev-list-n-parents:
tests: avoid nonportable {foo,bar} glob
rev-list --min-parents,--max-parents: doc, test and completion
revision.c: introduce --min-parents and --max-parents options
t6009: use test_commit() from test-lib.sh
This also adds test for "--merges" and "--no-merges" which we did not
have so far.
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* mg/rev-list-one-side-only:
git-log: put space after commit mark
t6007: test rev-list --cherry
log --cherry: a synonym
rev-list: documentation and test for --cherry-mark
revision.c: introduce --cherry-mark
rev-list/log: factor out revision mark generation
rev-list: --left/right-only are mutually exclusive
rev-list: documentation and test for --left/right-only
t6007: Make sure we test --cherry-pick
revlist.c: introduce --left/right-only for unsymmetric picking
Match the order of the description to the one in which they get applied:
commit limiting
commit ordering
commit formatting
diff options
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
At the porcelain level, because by definition there are many more contributors
than integrators, it makes sense to give a handy short-hand for --right-only
used with --cherry-mark and --no-merges. Make it so.
In other words, this provides "git cherry with rev-list interface".
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
They are applied after commit ordering and formatting options, in
particular --reverse.
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* mm/phrase-remote-tracking:
git-branch.txt: mention --set-upstream as a way to change upstream configuration
user-manual: remote-tracking can be checked out, with detached HEAD
user-manual.txt: explain better the remote(-tracking) branch terms
Change incorrect "remote branch" to "remote tracking branch" in C code
Change incorrect uses of "remote branch" meaning "remote-tracking"
Change "tracking branch" to "remote-tracking branch"
everyday.txt: change "tracking branch" to "remote-tracking branch"
Change remote tracking to remote-tracking in non-trivial places
Replace "remote tracking" with "remote-tracking"
Better "Changed but not updated" message in git-status
This may help to understand why --graph causes more comments to
be selected.
Signed-off-by: Yann Dirson <ydirson@altern.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Git's diff machinery has supported a -s (silence diff output) option
as far back as v0.99~900 (Silent flag for show-diff, 2005-04-13), but
the option is only advertised in an odd corner of the git diff-tree
manual.
The main use is to retrieve basic metadata about a commit:
git show -s rev
Explain this in the 'git log' manual and provide an example in the
'git show' examples section. This is kind of a cop-out, since it
would be more useful to explain it in the 'git show' manual proper,
which says:
The command takes options applicable to the git
diff-tree command to control how the changes the
commit introduces are shown.
This manual page describes only the most frequently
used options.
Fixing that is a larger task for another day.
Reported-by: Will Hall <will@gnatter.net>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
"remote-tracking" branch makes it explicit that the branch is "tracking a
remote", as opposed to "remote, and tracking something".
See discussion in e.g.
http://mid.gmane.org/8835ADF9-45E5-4A26-9F7F-A72ECC065BB2@gmail.com
for more details.
This patch is a straightforward application of
perl -pi -e 's/remote tracking branch/remote-tracking branch/'
except in the RelNotes directory.
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Remove some stray usage of other bracket types and asterisks for the
same purpose.
Signed-off-by: Štěpán Němec <stepnem@gmail.com>
Acked-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Make it clearer that --parents resp. --children list the parent resp.
child commits next to each commit, so that I understand next time.
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The symmetric difference or merge-base operator ... as used by
rev-list and diff is actually three period characters. If it
gets replaced by an ellipsis glyph in the manual, that would
stop readers from copying and pasting it.
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Add a --count option that, instead of actually listing the commits,
merely counts them.
This is mostly geared towards script use, and to this end it acts
specially when used with --left-right: it outputs the left and right
counts separately. Previously, scripts would have to run a shell loop
or small inline script over to achieve the same. (Without
--left-right, a simple |wc -l does the job.)
Signed-off-by: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Add a short paragraph explaining --ancestry-path, followed by a more
detailed example. This mirrors how the other history simplification options
are documented.
Signed-off-by: Johan Herland <johan@herland.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
In the detailed explanation of how the revision machinery does history
simplification, the current text presents an example history and explains
how various options of the revision machinery affect the resulting list
of commits. The first simplification mode mentioned is the default mode,
in which a number of commits is omitted from the example graph according
to the history simplification rules. The text states (among other things)
that commit "C was considered via N, but is TREESAME", and therefore
omitted. However, the accompanying graph does not list the effect on the
implicit parentage, i.e. that commit I takes C's place as a parent of N.
Running 'git rev-list --parents P' does indeed list I as a second parent
of N, and the accompanying graph should therefore also show this line.
Signed-off-by: Johan Herland <johan@herland.net>
Cc: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* pb/log-first-parent-p-m:
show --first-parent/-m: do not default to --cc
show -c: show patch text
revision: introduce setup_revision_opt
t4013: add tests for log -p -m --first-parent
git log -p -m: document -m and honor --first-parent
It is misleading to say that we pull refs from $GIT_DIR/refs/*, because we
may also consult the packed refs mechanism. These days we tend to treat
the "refs hierarchy" as more of an abstract namespace that happens to be
represented as $GIT_DIR/refs. At best, this is a minor inaccuracy, but at
worst it can confuse users who then look in $GIT_DIR/refs and find that it
is missing some of the refs they expected to see.
This patch drops most uses of "$GIT_DIR/refs/*", changing them into just
"refs/*", under the assumption that users can handle the concept of an
abstract refs namespace. There are a few things to note:
- most cases just dropped the $GIT_DIR/ portion. But for cases where
that left _just_ the word "refs", I changed it to "refs/" to help
indicate that it was a hierarchy. I didn't do the same for longer
paths (e.g., "refs/heads" remained, instead of becoming
"refs/heads/").
- in some cases, no change was made, as the text was explicitly about
unpacked refs (e.g., the discussion in git-pack-refs).
- In some cases it made sense instead to note the existence of packed
refs (e.g., in check-ref-format and rev-parse).
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
git log -p -m is used to show one merge entry per parent, with an
appropriate diff; this can be useful when examining histories where
full set of changes introduced by a merged branch is interesting, not
only the conflicts.
This patch properly documents the -m switch, which has so far been
mentioned only as a fairly special diff-tree flag.
It also makes the code show full patch entry only for the first parent
when --first-parent is used. Thus:
git log -p -m --first-parent
will show the history from the "main branch perspective", while also
including full diff of changes introduced by other merged in branches.
Signed-off-by: Petr Baudis <pasky@suse.cz>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Since local branch, tags and remote tracking branch namespaces are
most often used, add shortcut notations for globbing those in
manner similar to --glob option.
With this, one can express the "what I have but origin doesn't?"
as:
'git log --branches --not --remotes=origin'
Original-idea-by: Johannes Sixt <j6t@kdbg.org>
Signed-off-by: Ilari Liusvaara <ilari.liusvaara@elisanet.fi>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Add --glob=<glob-pattern> option to rev-parse and everything that
accepts its options. This option matches all refs that match given
shell glob pattern (complete with some DWIM logic).
Example:
'git log --branches --not --glob=remotes/origin'
To show what you have that origin doesn't.
Signed-off-by: Ilari Liusvaara <ilari.liusvaara@elisanet.fi>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
In commit ad3f9a7 (Add '--bisect' revision machinery argument) the
'--bisect' option was added to easily pass bisection refs to commands
using the revision machinery.
This patch updates the documentation of the related options to describe
the new behavior.
Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Similar to the command line arguments, after giving zero or more revs, you can
feed a line "--" and then feed pathspecs one at a time.
With this
(
echo ^maint
echo --
echo Documentation
) | git log --stat --oneline --stdin master -- t
lists commits that touch Documentation/ or t/ between maint and master.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Move the logic to read revs from standard input that rev-list knows about
from it to revision machinery, so that all the users of setup_revisions()
can feed the list of revs from the standard input when "--stdin" is used
on the command line.
Allow some users of the revision machinery that want different semantics
from the "--stdin" option to disable it by setting an option in the
rev_info structure.
This also cleans up the kludge made to bundle.c via cut and paste.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Other pages use --option=<argument>, not --option='argument', do the
same here.
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Talking about --date, one thing I wanted for the 1234567890 date was to
get things in the raw format. Sure, you get them with --pretty=raw, but it
felt a bit sad that you couldn't just ask for the date in raw format.
So here's a throw-away patch (meaning: I won't be re-sending it, because I
really don't think it's a big deal) to add "--date=raw". It just prints
out the internal raw git format - seconds since epoch plus timezone (put
another way: 'date +"%s %z"' format)
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Added simple descriptions of these options (based on description of --all).
Signed-off-by: Mark Burton <markb@ordern.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* lt/decorate:
rev-list documentation: clarify the two parts of history simplification
Document "git log --simplify-by-decoration"
Document "git log --source"
revision traversal: '--simplify-by-decoration'
Make '--decorate' set an explicit 'show_decorations' flag
revision: make tree comparison functions take commits rather than trees
Add a 'source' decorator for commits
Conflicts:
Documentation/rev-list-options.txt
One set of options and parameters determine what commits are involved in
the simplification process, and another set of options determine how the
simplification is done. Clarify their distinction at the beginning.
Signed-off-by: Santi Béjar <santi@agolina.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* maint:
Documentation: bisect: change a few instances of "git-cmd" to "git cmd"
Documentation: rev-list: change a few instances of "git-cmd" to "git cmd"
checkout: Don't crash when switching away from an invalid branch.
Jeff King
Carlos Martín Nieto
Junio C Hamano
Jack Nagel
Jonathan Nieder
Michael J Gruber
Yann Dirson
Matthieu Moy
Štěpán Němec
Thomas Rast
Johan Herland
Petr Baudis
Ralf Wildenhues
Ilari Liusvaara
Christian Couder
SZEDER Gábor
Linus Torvalds
Mark Burton
Santi Béjar
Nanako Shiraishi