summaryrefslogtreecommitdiff
path: root/Documentation/git-diff.txt
AgeCommit message (Collapse)AuthorFilesLines
2020-07-13git-diff.txt: reorder possible usagesLibravatar Martin Ågren1-6/+7
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>
2020-07-13git-diff.txt: don't mark required argument as optionalLibravatar Martin Ågren1-1/+1
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>
2020-06-12Documentation: usage for diff combined commitsLibravatar Chris Torek1-4/+16
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>
2019-11-02git-diff.txt: document return code of `--no-index`Libravatar Denton Liu1-1/+1
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>
2019-01-23doc: tidy asciidoc styleLibravatar Jean-Noël Avila1-9/+9
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>
2018-10-11doc: fix a typo and clarify a sentenceLibravatar Mihir Mehta1-2/+2
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>
2018-05-25Use proper syntax for replaceables in command docsLibravatar Robert P. J. Day1-13/+13
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>
2018-05-06doc: normalize [--options] to [options] in git-diffLibravatar Andreas Heiduk1-7/+7
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>
2018-05-06doc: align 'diff --no-index' in text and synopsisLibravatar Andreas Heiduk1-2/+2
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>
2017-04-13diff-files: document --ours etc.Libravatar Andreas Heiduk1-0/+14
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>
2014-03-31Documentation: fix misuses of "nor"Libravatar Justin Lebar1-2/+2
Signed-off-by: Justin Lebar <jlebar@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-02-05Documentation: fix typos in man pagesLibravatar Øystein Walle1-1/+1
Signed-off-by: Øystein Walle <oystwa@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-28diff --no-index: describe in a separate paragraphLibravatar Junio C Hamano1-5/+9
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>
2013-08-22diff --no-index: clarify operation when not inside a repositoryLibravatar Dale R. Worley1-1/+2
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>
2013-07-21Merge branch 'kb/diff-blob-blob-doc' into maintLibravatar Junio C Hamano1-7/+7
* kb/diff-blob-blob-doc: Documentation: Move "git diff <blob> <blob>"
2013-06-18Documentation: Move "git diff <blob> <blob>"Libravatar Kevin Bracey1-7/+7
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>
2013-02-01Documentation: the name of the system is 'Git', not 'git'Libravatar Thomas Ackermann1-1/+1
Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-12-18Documentation: Describe "git diff <blob> <blob>" separatelyLibravatar Junio C Hamano1-2/+7
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>
2011-03-11doc: drop author/documentation sections from most pagesLibravatar Jeff King1-8/+0
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.
2011-02-07diff: support --cached on unborn branchesLibravatar Nguyễn Thái Ngọc Duy1-0/+2
"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>
2010-11-05docs: clarify git diff modes of operationLibravatar Jeff King1-3/+8
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>
2010-11-05diff,difftool: Don't use the {0,2} notation in usage stringsLibravatar Štěpán Němec1-1/+1
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>
2010-10-13Documentation: update implicit "--no-index" behavior in "git diff"Libravatar Jonathan Nieder1-3/+3
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>
2010-10-13Documentation: expand 'git diff' SEE ALSO sectionLibravatar Jonathan Nieder1-2/+6
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>
2010-10-13Documentation: diff can compare blobsLibravatar Jonathan Nieder1-2/+3
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>
2010-10-13Documentation: gitrevisions is in section 7Libravatar Jonathan Nieder1-2/+2
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>
2010-07-05Documentation: link to gitrevisions rather than git-rev-parseLibravatar Michael J Gruber1-2/+2
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>
2010-01-09git-diff.txt: Link to git-difftoolLibravatar David Aguilar1-0/+4
Signed-off-by: David Aguilar <davvid@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-07-28Update the documentation of the raw diff output formatLibravatar David Kågedal1-2/+1
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>
2008-11-11git-diff: Add --staged as a synonym for --cached.Libravatar David Symonds1-0/+1
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-01Documentation: be consistent about "git-" versus "git "Libravatar Jonathan Nieder1-9/+9
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>
2008-06-06documentation: move git(7) to git(1)Libravatar Christian Couder1-1/+1
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>
2008-01-06Documentation: rename gitlink macro to linkgitLibravatar Dan McGee1-4/+4
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>
2007-11-15Documentation: customize diff-options depending on particular commandLibravatar Sergei Organov1-0/+1
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>
2007-11-02Merge branch 'gp/maint-diffdoc'Libravatar Junio C Hamano1-0/+3
* gp/maint-diffdoc: git-diff.txt: add section "output format" describing the diff formats
2007-11-01git-diff.txt: add section "output format" describing the diff formatsLibravatar Gerrit Pape1-0/+3
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>
2007-10-15Fix some typos, punctuation, missing words, minor markup.Libravatar Ralf Wildenhues1-1/+1
Signed-off-by: Lars Hjemli <hjemli@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-08-28Documentation/git-diff: A..B and A...B cannot take tree-ishesLibravatar Junio C Hamano1-5/+6
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>
2007-08-27Describe two-dot and three-dot notation for diff endpoints.Libravatar Mike Hommey1-7/+36
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-08-01Try to be consistent with capitalization in the documentationLibravatar Steve Hoelzer1-11/+11
Signed-off-by: Steve Hoelzer <shoelzer@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-07-28Documentation/git-diff: remove -r from --name-status exampleLibravatar Jeff King1-5/+2
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>
2007-06-07War on whitespaceLibravatar Junio C Hamano1-1/+0
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>
2007-03-05Merge branch 'master-for-junio' of git://repo.or.cz/git/fastimport; branch ↵Libravatar Junio C Hamano1-1/+1
'maint' * '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
2007-03-05Fix diff-options references in git-diff and git-format-patchLibravatar Brian Gernhardt1-1/+1
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>
2007-02-22Teach git-diff-files the new option `--no-index`Libravatar Johannes Schindelin1-0/+4
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>
2007-01-17Refer users to git-rev-parse for revision specification syntax.Libravatar Shawn O. Pearce1-0/+3
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>
2006-12-20diff documentation: mostly talk about <commit>Libravatar Junio C Hamano1-2/+2
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.
2006-12-15Make git-diff documentation use [--] when it should.Libravatar Brian Gernhardt1-3/+3
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>
2006-12-14Update git-diff documentationLibravatar Junio C Hamano1-17/+35
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>
2006-12-13Revert "git-diff: Introduce --index and deprecate --cached."Libravatar Junio C Hamano1-4/+2
This reverts commit 4c81c213a479e4aae0653a56ad6e8db5c31f019c. 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.