{"thread":{"id":"66756","subject":"[PATCH] doc: git-diff: rewrite EXAMPLES section","startedAt":"2026-11-03T15:33:27Z","lastAt":"2026-11-03T21:42:00Z","messageCount":7,"participants":["Julia Evans via GitGitGadget","Julia Evans","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"557324","messageId":"pull.2293.git.1793720007182.gitgitgadget@gmail.com","threadId":"66756","inReplyTo":null,"subject":"[PATCH] doc: git-diff: rewrite EXAMPLES section","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-11-03T15:33:27Z","receivedAt":"2026-11-03T15:33:27Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\nThe top piece of feedback users always give about man pages is always\nthat they want better examples that are relevant to them.\n\nThe EXAMPLES section's structure has remained mostly unchanged since\n2007, which was before we knew how people were going to use `git diff`.\nUpdate it with ways of using `git diff` that are popular with Git\nusers, gathered by asking Mastodon users for their most commonly used\nincantations.\n\nAdd a note about the EXAMPLES section in the DESCRIPTION since otherwise\nreaders are unlikely to know it's there. `git diff` is a command where\nit's more important than usual to have examples because the command has\nso many different forms.\n\nSome design choices:\n\n- Use `--merge-base` instead of `...` since several users said they\n find .. vs ... confusing. It's much more obvious what --merge-base\n does.\n- Use a table format instead of the footnote-style formatting since the\n footnote style is quite difficult to follow. It's easier to follow\n if the description is right next to the command it's describing.\n- Link the options in the examples to make them faster to look up\n- Use sub-subsection headings for the different parts to make\n them more visually distinct and easy to scan.\n\nCo-Authored-By: Marie Claire LeBlanc Flanagan \nSigned-off-by: Marie Claire LeBlanc Flanagan \nSigned-off-by: Julia Evans \n---\n doc: git-diff: rewrite EXAMPLES section\n \n A couple of self-review comments:\n \n * May want to add back the git diff AUTO_MERGE, nobody mentioned it but\n it's often nice to include 1 cool little-known example to try to\n promote it.\n * I'm not 100% sure about the table format, it does make it more\n compact which is really nice and makes it much more readable, but on\n an 80-character terminal there is some wrapping. One potential con is\n that it means we can't include as many details about what the command\n does. From my point of view that's a good thing because in a \"cheat\n sheet\" format it's very important to be concise, and people can\n always read the rest of the man page for the details.\n \n Here's what one of the tables looks like on an 80-character terminal\n with a little bit of wrapping.\n \n ┌─────────────────────────┬───────────────────────┐\n │Ignore all whitespace │ git diff │\n │changes │ --ignore-all-space │\n ├─────────────────────────┼───────────────────────┤\n │Show which individual │ git diff --word-diff │\n │words changed instead of │ │\n │the whole line │ │\n └─────────────────────────┴───────────────────────┘\n \n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2293%2Fjvns%2Fdiff-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2293/jvns/diff-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/2293\n\n Documentation/diff-options.adoc | 5 ++\n Documentation/git-diff.adoc | 149 ++++++++++++++++++--------------\n 2 files changed, 87 insertions(+), 67 deletions(-)\n\ndiff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc\nindex e605d28678..2dc54fa00e 100644\n--- a/Documentation/diff-options.adoc\n+++ b/Documentation/diff-options.adoc\n@@ -201,6 +201,7 @@ diff\" algorithm internally.\n \n include::diff-algorithm-option.adoc[]\n \n+[[stat]]\n `--stat[=[,[,]]]`::\n \tGenerate a diffstat. By default, as much space as necessary\n \twill be used for the filename part, and the rest for the graph\n@@ -318,12 +319,14 @@ Without this option, pathnames with \"unusual\" characters are quoted as\n explained for the configuration variable `core.quotePath` (see\n linkgit:git-config[1]).\n \n+[[name_only]]\n `--name-only`::\n \tShow only the name of each changed file in the post-image tree.\n \tThe file names are often encoded in UTF-8.\n \tFor more information see the discussion about encoding in the linkgit:git-log[1]\n \tmanual page.\n \n+[[name_status]]\n `--name-status`::\n \tShow only the name(s) and status of each changed file. See the description\n \tof the `--diff-filter` option on what the status letters mean.\n@@ -417,6 +420,7 @@ endif::git-diff[]\n \tIgnore changes in amount of whitespace. This ignores whitespace\n \tat line end, and considers all other sequences of one or\n \tmore whitespace characters to be equivalent.\n+[[ignore_all_space]]\n `ignore-all-space`::\n \tIgnore whitespace when comparing lines. This ignores differences\n \teven if one line has whitespace where the other line has none.\n@@ -432,6 +436,7 @@ endif::git-diff[]\n \tused to override configuration settings. It is the same as\n \t`--color-moved-ws=no`.\n \n+[[word_diff]]\n `--word-diff[=]`::\n \tBy default, words are delimited by whitespace; see\n \t`--word-diff-regex` below. The __ defaults to `plain`, and\ndiff --git a/Documentation/git-diff.adoc b/Documentation/git-diff.adoc\nindex 272331afba..8d9de30f64 100644\n--- a/Documentation/git-diff.adoc\n+++ b/Documentation/git-diff.adoc\n@@ -23,6 +23,9 @@ between the index and a tree, changes between two trees, changes resulting\n from a merge, changes between two blob objects, or changes between two\n files on disk.\n \n+The <> section has examples of the most common ways\n+to diff.\n+\n `git diff [] [--] [...]`::\n \n \tThis form is to view the changes you made relative to\n@@ -160,78 +163,90 @@ section \"3-Way Merge\" for detailed information.\n \n include::diff-format.adoc[]\n \n+[[EXAMPLES]]\n EXAMPLES\n --------\n \n-Various ways to check your working tree::\n-+\n-------------\n-$ git diff <1>\n-$ git diff --cached <2>\n-$ git diff HEAD <3>\n-$ git diff AUTO_MERGE <4>\n-------------\n-+\n-<1> Changes in the working tree not yet staged for the next commit.\n-<2> Changes between the index and your last commit; what you\n- would be committing if you run `git commit` without `-a` option.\n-<3> Changes in the working tree since your last commit; what you\n- would be committing if you run `git commit -a`\n-<4> Changes in the working tree you've made to resolve textual\n- conflicts so far.\n-\n-Comparing with arbitrary commits::\n-+\n-------------\n-$ git diff test <1>\n-$ git diff HEAD -- ./test <2>\n-$ git diff HEAD^ HEAD <3>\n-------------\n-+\n-<1> Instead of using the tip of the current branch, compare with the\n- tip of \"test\" branch.\n-<2> Instead of comparing with the tip of \"test\" branch, compare with\n- the tip of the current branch, but limit the comparison to the\n- file \"test\".\n-<3> Compare the version before the last commit and the last commit.\n-\n-Comparing branches::\n-+\n-------------\n-$ git diff topic master <1>\n-$ git diff topic..master <2>\n-$ git diff topic...master <3>\n-------------\n-+\n-<1> Changes between the tips of the topic and the master branches.\n-<2> Same as above.\n-<3> Changes that occurred on the master branch since when the topic\n- branch was started off it.\n+Diff uncommitted changes\n+~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+`git diff` will show the files from the \"before\" column as deleted and\n+from the \"after\" column as added.\n+\n+[cols=\"1,1\"]\n+|===\n+|Show unstaged changes\n+|`git diff`\n+\n+|Show staged changes\n+|`git diff --staged`\n+\n+|Show all changes since the latest commit\n+|`git diff HEAD`\n+|===\n+\n+Diff a specific file/directory\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+You can usually put a filename or directory at the end to restrict the\n+diff to that file/directory. You don't always need to put a `--`, but it\n+makes it unambiguous.\n+\n+[cols=\"1,1\"]\n+|===\n+|Show how `file.txt` has changed since `main`\n+|`git diff main -- file.txt`\n+\n+|Show unstaged changes for `file.txt`\n+|`git diff -- file.txt`\n+\n+|Show unstaged changes in `dir/`\n+|`git diff -- ./dir`\n+|===\n+\n+Diff branches or commits\n+~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+[cols=\"1,1\"]\n+|===\n+|Show changes on the `topic` branch since it branched off `main`\n+|`git diff --merge-base main topic`\n+\n+|Show changes between the `topic` branch and the `main` branch\n+|`git diff main topic`\n+\n+|Show changes between commit `ff11cc` and `HEAD`\n+|`git diff ff11cc HEAD`\n+|===\n+\n+Options to summarize the output\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+[cols=\"1,1\"]\n+|===\n+|Show how many lines in each file were changed\n+|`git diff` <>\n+\n+|Only show names of changed files\n+|`git diff` <>\n+\n+|Only show filenames and whether they were modified/deleted/added\n+|`git diff` <>\n+|===\n+\n+Options to display the diff in another way\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+[cols=\"1,1\"]\n+|===\n+|Ignore all whitespace changes\n+|`git diff` <>\n+\n+|Show which individual words changed instead of the whole line\n+|`git diff` <>\n+|===\n \n-Limiting the diff output::\n-+\n-------------\n-$ git diff --diff-filter=MRC <1>\n-$ git diff --name-status <2>\n-$ git diff arch/i386 include/asm-i386 <3>\n-------------\n-+\n-<1> Show only modification, rename, and copy, but not addition\n- or deletion.\n-<2> Show only names and the nature of change, but not actual\n- diff output.\n-<3> Limit diff output to named subtrees.\n \n-Munging the diff output::\n-+\n-------------\n-$ git diff --find-copies-harder -B -C <1>\n-$ git diff -R <2>\n-------------\n-+\n-<1> Spend extra cycles to find renames, copies and complete\n- rewrites (very expensive).\n-<2> Output diff in reverse.\n \n CONFIGURATION\n -------------\n\nbase-commit: 7e34d8174dcda3435d1404c9a30bef46afe6c13e\n-- \ngitgitgadget\n\n"},{"id":"557338","messageId":"57e9dc76-9cab-48e7-95c6-88868137202d@app.fastmail.com","threadId":"66756","inReplyTo":"pull.2293.git.1793720007182.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: git-diff: rewrite EXAMPLES section","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-11-03T17:16:14Z","receivedAt":"2026-11-03T17:16:14Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"> * I'm not 100% sure about the table format, it does make it more\n> compact which is really nice and makes it much more readable, but on\n> an 80-character terminal there is some wrapping. One potential con is\n> that it means we can't include as many details about what the command\n> does. From my point of view that's a good thing because in a \"cheat\n> sheet\" format it's very important to be concise, and people can\n> always read the rest of the man page for the details.\n\nWhile working on something else immediately after sending this,\nI learned that Asciidoc has support for horizontal definition lists\nwhich I think would make more sense than a table here.\nAnd they can be easily changed to a vertical definition list by\njust removing the [horizontal] if there's an issue in the future.\nhttps://docs.asciidoctor.org/asciidoc/latest/lists/horizontal/ \n\n"},{"id":"557364","messageId":"xmqqbj857l9r.fsf@gitster.g","threadId":"66756","inReplyTo":"pull.2293.git.1793720007182.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: git-diff: rewrite EXAMPLES section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-11-03T19:44:16Z","receivedAt":"2026-11-03T19:44:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" writes:\n\n> Here's what one of the tables looks like on an 80-character terminal\n> with a little bit of wrapping.\n> \n> ┌─────────────────────────┬───────────────────────┐\n> │Ignore all whitespace │ git diff │\n> │changes │ --ignore-all-space │\n> ├─────────────────────────┼───────────────────────┤\n> │Show which individual │ git diff --word-diff │\n> │words changed instead of │ │\n> │the whole line │ │\n> └─────────────────────────┴───────────────────────┘\n\nPersonally, I would not want to see these line-wrapped sentences in\ntables, which makes it impossible to cut-and-paste. But preferences\nvary from person to person, of course, on these things.\n\n> -Various ways to check your working tree::\n> -+\n> -------------\n> -$ git diff <1>\n> -$ git diff --cached <2>\n> -$ git diff HEAD <3>\n> -$ git diff AUTO_MERGE <4>\n> -------------\n> -+\n> -<1> Changes in the working tree not yet staged for the next commit.\n> -<2> Changes between the index and your last commit; what you\n> - would be committing if you run `git commit` without `-a` option.\n> -<3> Changes in the working tree since your last commit; what you\n> - would be committing if you run `git commit -a`\n> -<4> Changes in the working tree you've made to resolve textual\n> - conflicts so far.\n> ...\n> +[cols=\"1,1\"]\n> +|===\n> +|Show unstaged changes\n> +|`git diff`\n> +\n> +|Show staged changes\n> +|`git diff --staged`\n\nDo not sneak this change into an unrelated \"change the format to use\ntable to make it readable\" topic. Doing this change to just this\nsingle example would be a severe regression.\n\nLook at SYNOPSIS of \"git help diff\" and notice there is no mention\nof \"--staged\". The description on \"--cached\" explains it as a\nsynonym for it. If we wanted to promote \"--staged\" (which I would\nnot personally support), we'd need to do matching changes to the\nmain part of the text.\n\n> +|Show all changes since the latest commit\n> +|`git diff HEAD`\n> +|===\n\nYes, as you mentioned in the commentary, loss of AUTO_MERGE is a\nregression. I do not see a reason why you needed to drop it? Is it\nbecause some external limitation like you cannot have a table with\nmore than 3 rows or something?\n\nThanks.\n\n\n"},{"id":"557367","messageId":"9a6ae876-78d5-4513-8c75-c4c071c3db6a@app.fastmail.com","threadId":"66756","inReplyTo":"xmqqbj857l9r.fsf@gitster.g","subject":"Re: [PATCH] doc: git-diff: rewrite EXAMPLES section","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-11-03T19:52:16Z","receivedAt":"2026-11-03T19:52:16Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n>> +[cols=\"1,1\"]\n>> +|===\n>> +|Show unstaged changes\n>> +|`git diff`\n>> +\n>> +|Show staged changes\n>> +|`git diff --staged`\n>\n> Do not sneak this change into an unrelated \"change the format to use\n> table to make it readable\" topic. Doing this change to just this\n> single example would be a severe regression.\n\nI can change it back, I didn't realize it would be an issue.\n\nI changed it because several people said that they find `--cached`\nconfusing and that `--staged` was easier to understand because\nthat's the language Git normally uses in its UI when talking about\nstaged changes.\n\n> Look at SYNOPSIS of \"git help diff\" and notice there is no mention\n> of \"--staged\". The description on \"--cached\" explains it as a\n> synonym for it. If we wanted to promote \"--staged\" (which I would\n> not personally support), we'd need to do matching changes to the\n> main part of the text.\n>\n>> +|Show all changes since the latest commit\n>> +|`git diff HEAD`\n>> +|===\n>\n> Yes, as you mentioned in the commentary, loss of AUTO_MERGE is a\n> regression. I do not see a reason why you needed to drop it? Is it\n> because some external limitation like you cannot have a table with\n> more than 3 rows or something?\n\nI dropped it because I wanted to start with just the commands that\npeople said they found useful, and it can be hard to introduce\ntoo many \"new\" commands that aren't well-known already.\n\nThat said I think `git diff AUTO_MERGE` seems useful and I'm happy\nto put it back.\n\n"},{"id":"557370","messageId":"xmqqtslx64em.fsf@gitster.g","threadId":"66756","inReplyTo":"9a6ae876-78d5-4513-8c75-c4c071c3db6a@app.fastmail.com","subject":"Re: [PATCH] doc: git-diff: rewrite EXAMPLES section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-11-03T20:33:53Z","receivedAt":"2026-11-03T20:33:53Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" writes:\n\n>>> +|Show staged changes\n>>> +|`git diff --staged`\n>>\n>> Do not sneak this change into an unrelated \"change the format to use\n>> table to make it readable\" topic. Doing this change to just this\n>> single example would be a severe regression.\n>\n> I can change it back, I didn't realize it would be an issue.\n\nChanging this example alone without checking its fit in the wider\ncontext is what made it problematic. I do not personally support\n\"cached to staged\" because I consider it mostly a meaningless\nchurn, but that is different from saying I will veto it.\n\nI just wanted to see a bit more consistency; without changing the\nmain text, the change to the example made it look like a very odd\nthing to have there. You see the option named \"--staged\" but it\nis explained nowhere other than being a synonym to another option\nthat is much more widely explained.\n\n> I dropped it because I wanted to start with just the commands that\n> people said they found useful, and it can be hard to introduce\n> too many \"new\" commands that aren't well-known already.\n>\n> That said I think `git diff AUTO_MERGE` seems useful and I'm happy\n> to put it back.\n\nFWIW, what is in the current document was added by choosing what\nwere found useful. So you would want to think twice (note: this\nis very different from \"do not change\") before removing existing\nones or replacing them with something else. After spending a\nsignificant amount of effort on these documentation updates you are\nmaking, if a new person came and rewrote them again without\nunderstanding or paying much attention to your reasoning behind how\nyou arrived at your version, I would imagine that you would feel\nterrible. Please give the last person who wrote these documents\nthe same courtesy and respect.\n\nThanks.\n\n"},{"id":"557373","messageId":"ff8c1473-aaf0-4737-9ddc-5275e6ef70a2@app.fastmail.com","threadId":"66756","inReplyTo":"xmqqtslx64em.fsf@gitster.g","subject":"Re: [PATCH] doc: git-diff: rewrite EXAMPLES section","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-11-03T20:45:22Z","receivedAt":"2026-11-03T20:45:22Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n\nOn Tue, Nov 3, 2026, at 3:33 PM, Junio C Hamano wrote:\n> \"Julia Evans\" writes:\n>\n>>>> +|Show staged changes\n>>>> +|`git diff --staged`\n>>>\n>>> Do not sneak this change into an unrelated \"change the format to use\n>>> table to make it readable\" topic. Doing this change to just this\n>>> single example would be a severe regression.\n>>\n>> I can change it back, I didn't realize it would be an issue.\n>\n> Changing this example alone without checking its fit in the wider\n> context is what made it problematic. I do not personally support\n> \"cached to staged\" because I consider it mostly a meaningless\n> churn, but that is different from saying I will veto it.\n>\n> I just wanted to see a bit more consistency; without changing the\n> main text, the change to the example made it look like a very odd\n> thing to have there. You see the option named \"--staged\" but it\n> is explained nowhere other than being a synonym to another option\n> that is much more widely explained.\n>\n>> I dropped it because I wanted to start with just the commands that\n>> people said they found useful, and it can be hard to introduce\n>> too many \"new\" commands that aren't well-known already.\n>>\n>> That said I think `git diff AUTO_MERGE` seems useful and I'm happy\n>> to put it back.\n>\n> FWIW, what is in the current document was added by choosing what\n> were found useful. So you would want to think twice (note: this\n> is very different from \"do not change\") before removing existing\n> ones or replacing them with something else. After spending a\n> significant amount of effort on these documentation updates you are\n> making, if a new person came and rewrote them again without\n> understanding or paying much attention to your reasoning behind how\n> you arrived at your version, I would imagine that you would feel\n> terrible. Please give the last person who wrote these documents\n> the same courtesy and respect.\n\nIt's very hard to understand from the Git history the reasons for\nadding examples that were added 20 years ago, for example\nin 803f498c03b where these were added, especially since the commit\nmessages from 20 years ago tend to be a lot more terse.\n\n+Limiting the diff output::\n++\n+------------\n+$ git diff --diff-filter=MRC <1>\n+$ git diff --name-status -r <2>\n+$ git diff arch/i386 include/asm-i386 <3>\n\nI do hear that AUTO_MERGE was added more recently.\n\n"},{"id":"557380","messageId":"xmqq5wyd6193.fsf@gitster.g","threadId":"66756","inReplyTo":"ff8c1473-aaf0-4737-9ddc-5275e6ef70a2@app.fastmail.com","subject":"Re: [PATCH] doc: git-diff: rewrite EXAMPLES section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-11-03T21:42:00Z","receivedAt":"2026-11-03T21:42:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" writes:\n\n> It's very hard to understand from the Git history the reasons for\n> adding examples that were added 20 years ago, for example\n> in 803f498c03b where these were added, especially since the commit\n> messages from 20 years ago tend to be a lot more terse.\n\nSure. But that is why you send patches here to invite people to\ncomment on.\n\n> I do hear that AUTO_MERGE was added more recently.\n\n"}]}