The description of `git diff` goes through several different invocations
(numbering added by me):
1. git diff [<options>] [--] [<path>...]
2. git diff [<options>] --no-index [--] <path> <path>
3. git diff [<options>] --cached [<commit>] [--] [<path>...]
4. git diff [<options>] <commit> [--] [<path>...]
5. git diff [<options>] <commit> <commit> [--] [<path>...]
6. git diff [<options>] <commit>..<commit> [--] [<path>...]
7. git diff [<options>] <commit> <commit>... <commit> [--] [<path>...]
8. git diff [<options>] <commit>...<commit> [--] [<path>...]
It then goes on to say that "all of the <commit> in the above
description, except in the last two forms that use '..' notations, can
be any <tree>". The "last two" actually refers to 6 and 8. This got out
of sync in commit b7e10b2ca2 ("Documentation: usage for diff combined
commits", 2020-06-12) which added item 7 to the mix.
As a further complication, after b7e10b2ca2 we also have some potential
confusion around "the '..' notation". The "..[.]" in items 6 and 8 are
part of the rev notation, whereas the "..." in item 7 is manpage
language for "one or more".
Move item 6 down, i.e., to between 7 and 8, to restore the ordering.
Because 6 refers to 5 ("synonymous to the previous form") we need to
tweak the language a bit.
An added bonus of this commit is that we're trying to steer users away
from `git diff <commit>..<commit>` and moving it further down probably
doesn't hurt.
Signed-off-by: Martin Ågren <martin.agren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Commit b7e10b2ca2 ("Documentation: usage for diff combined commits",
2020-06-12) modified the synopsis by adding an optional "[<commit>...]"
to
'git diff' [<options>] <commit> <commit> [--] [<path>...]
to effectively add
'git diff' [<options>] <commit> <commit>... <commit> [--] [<path>...]
as another valid invocation. Which makes sense.
Further down, in the description, it left the existing entry for
'git diff' [<options>] <commit> <commit> [--] [<path>...]
intact and added a new entry on
'git diff' [<options>] <commit> [<commit>...] <commit> [--] [<path>...]
where it says that "[t]his form is to view the results of a merge
commit" and details how "the first listed commit must be the merge
itself". But one possible instantiation of this form is `git diff
<commit> <commit>` for which the added text doesn't really apply.
Remove the brackets so that we lose this overlap between the two
descriptions. We can still use the more compact representation in the
synopsis.
Signed-off-by: Martin Ågren <martin.agren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Document the usage for producing combined commits with "git diff".
This includes updating the synopsis section.
While here, add the three-dot notation to the synopsis.
Make "git diff -h" print the same usage summary as the manual
page synopsis, minus the "A..B" form, which is now discouraged.
Signed-off-by: Chris Torek <chris.torek@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Within diff_no_index(), we have the following:
revs->diffopt.flags.exit_with_status = 1;
...
/*
* The return code for --no-index imitates diff(1):
* 0 = no changes, 1 = changes, else error
*/
return diff_result_code(&revs->diffopt, 0);
Which means when `git diff` is run in `--no-index` mode, `--exit-code`
is implied. However, the documentation for this is missing in
git-diff.txt.
Add a note about how `--exit-code` is implied in the `--no-index`
documentation to cover this documentation blindspot.
Signed-off-by: Denton Liu <liu.denton@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This mainly refers to enforcing indentation on additional lines of
items of lists.
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
I noticed that git-merge-base was unlikely to actually be a git command,
and tried it in my shell. Seeing that it doesn't work, I cleaned up two
places in the docs where it appears.
Signed-off-by: Mihir Mehta <mihir@cs.utexas.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The standard for command documentation synopses appears to be:
[...] means optional
<...> means replaceable
[<...>] means both optional and replaceable
So fix a number of doc pages that use incorrect variations of the
above.
Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
SYNOPSIS and other manuals use [options] but DESCRIPTION
used [--options].
Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Make the two '<path>' parameters in DESCRIPTION mandatory and
move the `--options` part to the same place where the other
variants show them. And finally make `--no-index` in SYNOPSIS
as mandatory as in DESCRIPTION.
Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
Reviewed-by: Martin Ågren <martin.agren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
git-diff understands "--ours", "--theirs" and "--base" for files with
conflicts. But so far they were not documented for the central diff
command but only for diff-files.
Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The documentation for "diff-files" mode of "git diff" primarily
talks about how changes in the files in the working tree are shown
relative to the contents previously added to that index, and tucks
explanation on how "--no-index" mode, which works in a quite
different way, may be implicitly used instead. Instead, add a
separate paragraph to explain what "--no-index" mode does, and also
mention when "--no-index" can be omitted from the command line
(essentially, when it is obvious from the context).
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Clarify documentation for "diff --no-index". State that when not
inside a repository, --no-index is implied and two arguments are
mandatory.
Clarify error message from diff-no-index to inform user that CWD is
not inside a repository and thus two arguments are mandatory.
Signed-off-by: Dale Worley <worley@ariadne.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The section describing "git diff <blob> <blob>" had been placed in a
position that disrupted the statement "This is synonymous to the
previous form".
Reorder to place this form after all the <commit>-using forms, and the
note applying to them. Also mention this form in the initial description
paragraph.
Signed-off-by: Kevin Bracey <kevin@bracey.fi>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
As it was not a common operation, it was described as if it is a
side note for the more common two-commit variant, but this mode
behaves very differently, e.g. it does not make any sense to ask
recursive behaviour, or give the command a pathspec.
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.
"git diff --cached" (without revision) used to mean "git diff --cached
HEAD" (i.e. the user was too lazy to type HEAD). This "correctly"
failed when there was no commit yet. But was that correctness useful?
This patch changes the definition of what particular command means.
It is a request to show what _would_ be committed without further "git
add". The internal implementation is the same "git diff --cached HEAD"
when HEAD exists, but when there is no commit yet, it compares the index
with an empty tree object to achieve the desired result.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
It is an oversimplification to say that we can take
"[<commit> [<commit>]]", as it really depends on what
options have been given. Instead, let's list the major modes
of operation separately, as we do in other manpages.
This patch also adjusts the text immediately after the
synopsis to match the lines given in the synopsis.
For git-difftool, which has the same issue, let's refer the
user to the git-diff manpage rather than spelling it all out
again.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This was the only occurence of that usage, and square brackets are
sufficient and already well-established for that purpose.
Signed-off-by: Štěpán Němec <stepnem@gmail.com>
Acked-by: Sverre Rabbelier <srabbelier@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Originally "--no-index" mode triggered for untracked files within the
tracked tree, but with v1.5.6-rc1~41 (Merge branch 'jc/diff-no-no-index,
2008-05-26) the command was fixed to only implicitly trigger when paths
outside the tracked tree are mentioned.
Reported-by: Yann Dirson <dirson@bertin.fr>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Point in many directions in the hope of helping the reader find what
is needed more quickly.
This commit also removes the summary attached to the SEE ALSO entry
for difftool, to avoid making the SEE ALSO list too verbose. If the
reader wants a summary of the commands referred to, she can always
look to the top of the named pages or to the table of contents on the
main git(1) page.
Suggested-by: Goswin von Brederlow <goswin-v-b@web.de>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Meanwhile, there is no plumbing command to compare two blobs.
Strange.
Reported-by: Yann Dirson <dirson@bertin.fr>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Fix references to gitrevisions(1) in the manual pages and HTML
documentation.
In practice, this will not matter much unless someone tries to use a
hard copy of the git reference manual.
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Currently, whenever we need documentation for revisions and ranges, we
link to the git-rev-parse man page, i.e. a plumbing man page, which has
this along with the documentation of all rev-parse modes.
Link to the new gitrevisions man page instead in all cases except
- when the actual git-rev-parse command is referred to or
- in very technical context (git-send-pack).
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This includes mentioning the initial hash output of diff-tree, and
changes the header to "raw output format" which is more descriptive.
Signed-off-by: David Kågedal <davidk@lysator.liu.se>
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>
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>
Customize diff-options depending on particular command as follows,
mostly to make git-diff and git-format-patch manuals less confusing:
* git-format-patch:
- Mark --patch-with-stat as being the default.
- Change -p description so that it matches what it actually does and
so that it doesn't refer to absent "section on generating
patches".
* git-diff: mark -p as being the default.
* git-diff-index/git-diff-files/git-diff-tree: mark --raw as being
the default.
Signed-off-by: Sergei Organov <osv@javad.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
git-diff.txt includes diff-options.txt which for the -p option refers
to a section "generating patches.." which is missing from the git-diff
documentation. This patch adapts diff-format.txt to additionally
mention the git-diff program, and includes diff-format.txt into
git-diff.txt.
Tino Keitel noticed this problem.
Signed-off-by: Gerrit Pape <pape@smarden.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
As pointed out by Linus, these notations require the endpoints
given by the end user to be commits. Clarify.
Also, three-dots in AsciiDoc are turned into ellipses unless
quoted with bq. Be careful.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Calling 'git-diff --name-status' will recursively show any
changes already, and it has for quite some time (at least as
far back as v1.4.1).
Signed-off-by: Jeff King <peff@peff.net>
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>
* 'master-for-junio' of git://repo.or.cz/git/fastimport:
fast-import: Fail if a non-existant commit is used for merge
fast-import: Avoid infinite loop after reset
* maint:
Fix diff-options references in git-diff and git-format-patch
Add definition of <commit-ish> to the main git man page.
Begin SubmittingPatches with a check list
fast-import: Fail if a non-existant commit is used for merge
fast-import: Avoid infinite loop after reset
Most of the git-diff-* documentation used [<common diff options>]
instead of [--diff-options], so make that change in git-diff and
git-format-patch.
In addition, git-format-patch didn't include the meanings of the diff
options.
Signed-off-by: Brian Gernhardt <benji@silverinsanity.com>
Signed-off-by: Junio C Hamano <junkio@cox.net>
With this flag and given two paths, git-diff-files behaves as a GNU diff
lookalike (plus the git goodies like --check, colour, etc.). This flag
is also available in git-diff. It also works outside of a git repository.
In addition, if git-diff{,-files} is called without revision or stage
parameter, and with exactly two paths at least one of which is not tracked,
the default is --no-index.
So, you can now say
git diff /etc/inittab /etc/fstab
and it actually works!
This also unifies the duplicated argument parsing between cmd_diff_files()
and builtin_diff_files().
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Signed-off-by: Junio C Hamano <junkio@cox.net>
The revision specification syntax (sometimes referred to as
SHA1-expressions) is accepted almost everywhere in Git by
almost every tool. Unfortunately it is only documented in
git-rev-parse.txt, and most users don't know to look there.
Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
Signed-off-by: Junio C Hamano <junkio@cox.net>
This corrects minor remaining bits that still talked about <tree-ish>;
the Porcelain users (as opposed to plumbers) are mostly interested in
commits so use <commit> consistently and keep a sentence that mentions
that <tree-ish> can be used in place of them.
Two of the cases has "[--] [<path>...]" and two had "-- [<path>...]".
Not terribly consistent and potentially confusing. Also add "[--]" to
the synopsis so that it's obvious you can use it from the very
beginning.
Signed-off-by: Brian Gernhardt <benji@silverinsanity.com>
Signed-off-by: Junio C Hamano <junkio@cox.net>
Porcelain documentation should talk in terms of end-user workflow, not
in terms of implementation details. Do not suggest update-index, but
git-add instead. Explain differences among 0-, 1- and 2-tree cases
not as differences of number of trees given to the command, but say
why user would want to give these number of trees to the command in
what situation.
Signed-off-by: Junio C Hamano <junkio@cox.net>
This reverts commit 4c81c213a4.
Although --cached and --index are confusing wording, the use of
word --cached for git-diff is consistent with git-apply. It means
"work with index without looking at the working tree".
We should probably come up with better wording for --cached, if
somebody wants to deprecate it. But making --index and --cached
synonyms for diff while leaving them mean different things for
apply is no good.
