git/Documentation/diff-format.txt, branch v2.48.2

doc: git-diff: apply format changes to diff-format

2024-11-19T03:31:04Z

Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano

diff-format.txt: correct misleading wording

2022-06-13T18:57:03Z

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: 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: 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 '' 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

diff-format.txt: dst can be 0* SHA-1 when path is deleted, too

2022-06-13T18:23:13Z

"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

Documentation/diff-format: state in which cases porcelain status is T

2021-10-04T20:07:18Z

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

doc: indent multi-line items in list

2019-12-13T20:18:07Z

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

log,diff-tree: add --combined-all-paths option

2019-02-08T04:15:25Z

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 bar.sh ::100644 100644 100644 e07d6c5 9042e82 ee91881 RR phooey.c This doesn't let us know what the original name of bar.sh 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 foo.sh bar.sh bar.sh ::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

doc: update diff-format.txt for removed ellipses in --raw

2018-11-26T06:59:14Z

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

Documentation: improve description for core.quotePath

2017-03-02T19:40:51Z

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

doc: typeset long command-line options as literal

2016-06-28T15:36:45Z

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

doc: typeset short command-line options as literal

2016-06-28T15:20:52Z

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