path: root/Documentation/diff-format.txt
AgeCommit message (Collapse)Author
2022-06-13diff-format.txt: correct misleading wordingPhilippe Blain
Near the end of the "Raw output format" section, an example shows the output of 'git diff-files' for a tracked file modified on disk but not yet added to the index. However the wording is: <sha1> is shown as all 0's if a file is new on the filesystem and it is out of sync with the index. which is confusing since it can be understood to mean that 'file' is a new, yet untracked file, in which case 'git diff-files' does not care about it at all. When this example was introduced all the way back in c64b9b8860 (Reference documentation for the core git commands., 2005-05-05), 'old' and 'new' referred to the two entities being compared, depending on the command being used (diff-index, diff-tree or diff-files - which at the time were diff-cache, diff-tree and show-diff). The wording used at the time was: <new-sha1> is shown as all 0's if new is a file on the filesystem and it is out of sync with the cache. This section was reworked in 81e50eabf0 ([PATCH] The diff-raw format updates., 2005-05-21) and the mention of the meaning of 'new' and 'old' was removed. Then in f73ae1fc5d (Some typos and light editing of various manpages, 2005-10-05), the wording was changed to what it is now. In addition, in b6d8f309d9 ([PATCH] diff-raw format update take #2., 2005-05-23), the section was further reworked and did not use '<sha1>' anymore, making the example the sole user of this token. Rework the introductory sentence of the example to instead refer to 'sha1 for "dst"', which is what the text description above it uses, and fix the wording so that we do not mention a "new file". While at it, also tweak the wording used in the description of the raw format to explicitely state that all 0's are used for the destination hash if the working tree is out of sync with the index, instead of the more vague "look at worktree". Signed-off-by: Philippe Blain <> Signed-off-by: Junio C Hamano <>
2022-06-13diff-format.txt: dst can be 0* SHA-1 when path is deleted, tooPhilippe Blain
"dst" can legitimately be "0\{40\}" for a creation patch, e.g. when the stat information is stale, but it falls into "look at work tree" case. The original description in b6d8f309 ([PATCH] diff-raw format update take #2., 2005-05-23) forgot that deletion also makes the "dst" 0* SHA-1. Signed-off-by: Philippe Blain <> Signed-off-by: Junio C Hamano <>
2021-10-04Documentation/diff-format: state in which cases porcelain status is TJohannes Altmanninger
Porcelain status letter T is documented as "type of the file", which is technically correct but not enough information for users that are not so familiar with this term from systems programming. In particular, given that the only supported file types are "regular file", "symbolic link" and "submodule", the term "file type" is surely opaque to the many(?) users who are not aware that symbolic links can be tracked - I thought that a "chmod +x" could cause the T status (wrong, it's M). Explicitly document the three file types so users know if/how they want to handle this. Signed-off-by: Johannes Altmanninger <> Signed-off-by: Junio C Hamano <>
2019-12-13doc: indent multi-line items in listJean-Noël Avila
Although Asciidoc allows to not indent following lines in a list item, it is clearer and safer to follow the recommended rule. Signed-off-by: Jean-Noël Avila <> Signed-off-by: Junio C Hamano <>
2019-02-08log,diff-tree: add --combined-all-paths optionElijah Newren
The combined diff format for merges will only list one filename, even if rename or copy detection is active. For example, with raw format one might see: ::100644 100644 100644 fabadb8 cc95eb0 4866510 MM describe.c ::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM ::100644 100644 100644 e07d6c5 9042e82 ee91881 RR phooey.c This doesn't let us know what the original name of was in the first parent, and doesn't let us know what either of the original names of phooey.c were in either of the parents. In contrast, for non-merge commits, raw format does provide original filenames (and a rename score to boot). In order to also provide original filenames for merge commits, add a --combined-all-paths option (which must be used with either -c or --cc, and is likely only useful with rename or copy detection active) so that we can print tab-separated filenames when renames are involved. This transforms the above output to: ::100644 100644 100644 fabadb8 cc95eb0 4866510 MM desc.c desc.c desc.c ::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM ::100644 100644 100644 e07d6c5 9042e82 ee91881 RR fooey.c fuey.c phooey.c Further, in patch format, this changes the from/to headers so that instead of just having one "from" header, we get one for each parent. For example, instead of having --- a/phooey.c +++ b/phooey.c we would see --- a/fooey.c --- a/fuey.c +++ b/phooey.c Signed-off-by: Elijah Newren <> Signed-off-by: Junio C Hamano <>
2018-11-26doc: update diff-format.txt for removed ellipses in --rawGreg Hurrell
Since 7cb6ac1e4b ("diff: diff_aligned_abbrev: remove ellipsis after abbreviated SHA-1 value", 2017-12-03), the "--raw" format of diff does not add ellipses in an attempt to align the output, but the documentation was not updated to reflect this. Signed-off-by: Greg Hurrell <> Signed-off-by: Junio C Hamano <>
2017-03-02Documentation: improve description for core.quotePathAndreas Heiduk
Linking the description for pathname quoting to the configuration variable "core.quotePath" removes inconstistent and incomplete sections while also giving two hints how to deal with it: Either with "-c core.quotePath=false" or with "-z". Signed-off-by: Andreas Heiduk <> Signed-off-by: Junio C Hamano <>
2016-06-28doc: typeset long command-line options as literalMatthieu Moy
Similarly to the previous commit, use backquotes instead of forward-quotes, for long options. This was obtained with: perl -pi -e "s/'(--[a-z][a-z=<>-]*)'/\`\$1\`/g" *.txt and manual tweak to remove false positive in ascii-art (o'--o'--o' to describe rewritten history). Signed-off-by: Matthieu Moy <> Signed-off-by: Junio C Hamano <>
2016-06-28doc: typeset short command-line options as literalMatthieu Moy
It was common in our documentation to surround short option names with forward quotes, which renders as italic in HTML. Instead, use backquotes which renders as monospace. This is one more step toward conformance to Documentation/CodingGuidelines. This was obtained with: perl -pi -e "s/'(-[a-z])'/\`\$1\`/g" *.txt Signed-off-by: Matthieu Moy <> Signed-off-by: Junio C Hamano <>
2015-01-29diff-format doc: a score can follow M for rewriteJunio C Hamano
b6d8f309 (diff-raw format update take #2., 2005-05-23) started documenting the diff format, and it said ... (8) sha1 for "dst"; 0{40} if creation, unmerged or "look at work tree". (9) status, followed by similarlity index number only for C and R. (10) a tab or a NUL when '-z' option is used. ... because C and R _were_ the only ones that came with a number back then. This was corrected by ddafa7e9 (diff-helper: Fix R/C score parsing under -z flag., 2005-05-29) and we started saying "score" instead of "similarlity index" (because we can have other kind of score there), and stopped saying "only for C and R" (because Git is an ever evolving system). Later f345b0a0 (Add -B flag to diff-* brothers., 2005-05-30) introduced a new concept, "dissimilarity" score; it did not have to fix any documentation. The current text that says only C and R can have scores came independently from a5a323f3 (Add reference for status letters in documentation., 2008-11-02) and it was wrong from the day one. Noticed-by: Mike Hommey Signed-off-by: Junio C Hamano <>
2010-01-31Fix typos in technical documentation.Ralf Wildenhues
Signed-off-by: Ralf Wildenhues <> Signed-off-by: Junio C Hamano <>
2009-07-28Update the documentation of the raw diff output formatDavid Kågedal
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 <> Signed-off-by: Junio C Hamano <>
2008-12-20Documentation: fix typos, grammar, asciidoc syntaxMarkus Heidelberg
Signed-off-by: Markus Heidelberg <> Signed-off-by: Junio C Hamano <>
2008-11-02Add reference for status letters in documentation.Yann Dirson
Also fix error in diff_filepair::status documentation, and point to the in-code reference as well as the doc. Signed-off-by: Yann Dirson <> Signed-off-by: Junio C Hamano <>
2007-12-12git-diff --numstat -z: make it machine readableJunio C Hamano
The "-z" format is all about machine parsability, but showing renamed paths as "common/{a => b}/suffix" makes it impossible. The scripts would never have successfully parsed "--numstat -z -M" in the old format. This fixes the output format in a (hopefully minimally) backward incompatible way. * The output without -z is not changed. This has given a good way for humans to view added and deleted lines separately, and showing the path in combined, shorter way would preserve readability. * The output with -z is unchanged for paths that do not involve renames. Existing scripts that do not pass -M/-C are not affected at all. * The output with -z for a renamed path is shown in a format that can easily be distinguished from an unrenamed path. This is based on Jakub Narebski's patch. Bugs and documentation typos are mine. Signed-off-by: Junio C Hamano <>
2007-12-05Include diff options in the git-log manpageMiklos Vajna
[jc: with quite a few fixups] Signed-off-by: Miklos Vajna <> Signed-off-by: Junio C Hamano <>
2007-11-02git-diff.txt: add section "output format" describing the diff formatsGerrit Pape
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 <> Signed-off-by: Junio C Hamano <>
2007-06-25diff: round down similarity indexRené Scharfe
Rounding down the printed (dis)similarity index allows us to use "100%" as a special value that indicates complete rewrites and fully equal file contents, respectively. Signed-off-by: Rene Scharfe <> Signed-off-by: Junio C Hamano <>
2007-06-07War on whitespaceJunio C Hamano
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 <>
2007-05-04diff format documentation: describe raw combined diff formatJakub Narebski
Add description of raw combined diff format to diff-formats.txt, as "diff format for merges" section, before "Generating patches..." section. Signed-off-by: Jakub Narebski <> Signed-off-by: Junio C Hamano <>
2007-02-04Assorted typo fixesPavel Roskin
Signed-off-by: Junio C Hamano <>
2006-11-27Update documentation to remove incorrect GIT_DIFF_OPTS example.Sean
Git no longer calls an external diff program to generate patches. Remove the documentation which suggests that you can pass arbitrary diff options via the GIT_DIFF_OPTS environment variable. Signed-off-by: Sean Estabrooks <> Signed-off-by: Junio C Hamano <>
2006-10-27Merge branch 'jc/combined' into maintJunio C Hamano
* jc/combined: combine-diff: honour --no-commit-id combine-diff: fix hunk_comment_line logic. combine-diff: a few more finishing touches.
2006-10-27diff-format.txt: Correct information about pathnames quoting in patch formatJakub Narebski
Signed-off-by: Jakub Narebski <> Signed-off-by: Junio C Hamano <>
2006-10-26combine-diff: a few more finishing touches.Junio C Hamano
"new file" and "deleted file" were already reported in the original code, but the logic was not as transparent as it could have. This uses a few variables and more comments to clarify the flow. The rule is: (1) if a path exists in the merge result when no parent had it, we report "new" (otherwise it came from the parents, as opposed to have added by the evil merge). (2) if the path does not exist in the merge result, it is "deleted". Since we can say "new" and "deleted", there is no reason not to follow the /dev/null convention. This fixes it. Appending function name after @@@ ... @@@ is trivial, so implement it. Signed-off-by: Junio C Hamano <>
2006-10-26diff-format.txt: Combined diff format documentation supplementJakub Narebski
Update example combined diff format to the current version $ git diff-tree -p -c fec9ebf16c948bcb4a8b88d0173ee63584bcde76 and provide complete first chunk in example. Document combined diff format headers: how "diff header" look like, which of "extended diff headers" are used with combined diff and how they look like, differences in two-line from-file/to-file header from non-combined diff format, chunk header format. It should be noted that combined diff format was designed for quick _content_ inspection and renames would work correctly to pick which blobs from each tree to compare but otherwise not reflected in the output (the pathnames are not shown). [jc: with minimum copyediting] Signed-off-by: Jakub Narebski <> Signed-off-by: Junio C Hamano <>
2006-01-28Documentation: diff -c/--ccJunio C Hamano
Signed-off-by: Junio C Hamano <>
2005-12-29Documentation: spell.Junio C Hamano
Signed-off-by: Junio C Hamano <>
2005-11-17GIT 0.99.9j aka 1.0rc3v1.0rc3v0.99.9jJunio C Hamano
Signed-off-by: Junio C Hamano <>
2005-11-11Change 'cache' to 'index' in the docsLukas_Sandström
This patch makes the documentation refer to the index as index instead of cache, but some references still remain. (e.g. git-update-index.txt) Signed-off-by: Lukas Sandström <> Signed-off-by: Junio C Hamano <>
2005-10-18Update documentation for C-style quoting.Junio C Hamano
Signed-off-by: Junio C Hamano <>
2005-10-10Convert usage of GIT and Git into gitChristian Meder
Convert usage of GIT and Git into git. Signed-off-by: Christian Meder <> Signed-off-by: Junio C Hamano <>
2005-10-05Some typos and light editing of various manpagesChristian Meder
Typos, light editing and clarifications. Signed-off-by: Christian Meder <> Signed-off-by: Junio C Hamano <>
2005-09-22Retire diff-helper.Junio C Hamano
The textual diff generation with built-in '-p' in diff-* brothers has proven to be useful enough that git-diff-helper outlived its usefulness. Signed-off-by: Junio C Hamano <>
2005-09-08Big tool rename.Junio C Hamano
As promised, this is the "big tool rename" patch. The primary differences since 0.99.6 are: (1) git-*-script are no more. The commands installed do not have any such suffix so users do not have to remember if something is implemented as a shell script or not. (2) Many command names with 'cache' in them are renamed with 'index' if that is what they mean. There are backward compatibility symblic links so that you and Porcelains can keep using the old names, but the backward compatibility support is expected to be removed in the near future. Signed-off-by: Junio C Hamano <>
2005-08-30Documentaion updates.Junio C Hamano
Mostly making the formatted html prettier. Signed-off-by: Junio C Hamano <> (cherry picked from 7adf1f15ebe074d4767df941817a6cf86d8e2533 commit)
2005-08-06[PATCH] Assorted documentation patchesJohannes Schindelin
[jc: Johannes spent time and effort to see how consistent our use of terminilogy is, and as a byproduct made these corrections not related to the terminology unification. I really appreciate it.] Signed-off-by: Johannes Schindelin <> Signed-off-by: Junio C Hamano <>
2005-06-08[PATCH] Miniscule correction of diff-format.txtChristian Meder
Add missing "space" element to the description of the diff-format. Signed-off-by: Christian Meder <> Acked-by: Petr Baudis <> Signed-off-by: Linus Torvalds <>
2005-06-05[PATCH] Documentation: describe git extended diff headers.Junio C Hamano
The documentation failed to describe "diff --git" extended diff headers, so add some. Signed-off-by: Junio C Hamano <> Signed-off-by: Linus Torvalds <>
2005-05-30[PATCH] diff-helper: Fix R/C score parsing under -z flag.Junio C Hamano
The score number that follow R/C status were parsed but the parse pointer was not updated, causing the entire line to become unrecognized. This patch fixes this problem. There was a test missing to catch this breakage, which this commit adds as The diff-raw tests used in related (the same test without -z) and were stricter than necessarily, despite that the comment for the tests said otherwise. This patch also corrects them. The documentation is updated to say that the status can optionally be followed by a number called "score"; it does not have to stay similarity index forever and there is no reason to limit it only to C and R. Signed-off-by: Junio C Hamano <> Signed-off-by: Linus Torvalds <>
2005-05-23[PATCH] diff-raw format update take #2.Junio C Hamano
This changes the diff-raw format again, following the mailing list discussion. The new format explicitly expresses which one is a rename and which one is a copy. The documentation and tests are updated to match this change. Signed-off-by: Junio C Hamano <> Signed-off-by: Linus Torvalds <>
2005-05-22[PATCH] The diff-raw format updates.Junio C Hamano
Update the diff-raw format as Linus and I discussed, except that it does not use sequence of underscore '_' letters to express nonexistence. All '0' mode is used for that purpose instead. The new diff-raw format can express rename/copy, and the earlier restriction that -M and -C _must_ be used with the patch format output is no longer necessary. The patch makes -M and -C flags independent of -p flag, so you need to say git-whatchanged -M -p to get the diff/patch format. Updated are both documentations and tests. Signed-off-by: Junio C Hamano <> Signed-off-by: Linus Torvalds <>
2005-05-15[PATCH 2/3] Rename git-diff-tree-helper to git-diff-helper.Junio C Hamano
It used to be that diff-tree needed helper support to parse its raw output to generate diffs, but these days git-diff-* family produces the same output and the helper is not tied to diff-tree anymore. Drop "tree" from its name. This commit is done separately to record just the rename and no file content changes. The changes in the renamed files are recorded in the next commit. Signed-off-by: Junio C Hamano <> Bundled with the changes in the unrenamed files. Signed-off-by: Petr Baudis <>
2005-05-10[PATCH 1/4] split core-git.txt and updateDavid Greaves
Split the core-git.txt file Formatting fix to the diff-format.txt Signed-off-by: David Greaves <>
2005-05-08[PATCH 2/2] core-git documentation updateDavid Greaves
Reformat core-git.txt to asciidoc format. Includes to create individual txt, html and man pages. <JC> Editorial note. I've updated to add git-diff-cache -m and git-update-cache --replace description on top of the version David posted to the GIT list and got his OK. Signed-off-by: David Greaves <> Signed-off-by: Junio C Hamano <>