{"thread":{"id":"63947","subject":"[PATCH 0/5] doc: git-add: clarify DESCRIPTION section","startedAt":"2025-08-12T20:07:32Z","lastAt":"2025-08-29T17:11:36Z","messageCount":59,"participants":["Julia Evans via GitGitGadget","Junio C Hamano","Chris Torek","Julia Evans","D. Ben Knoble","Jean-Noël AVILA","Junio C Hamano via GitGitGadget","rsbecker@nexbridge.com"],"isPatch":true,"patchVersion":1,"patchTotal":5},"messages":[{"id":"524083","messageId":"pull.1952.git.1755029249.gitgitgadget@gmail.com","threadId":"63947","inReplyTo":null,"subject":"[PATCH 0/5] doc: git-add: clarify DESCRIPTION section","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-12T20:07:24Z","receivedAt":"2025-08-12T20:07:32Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"This patch series aims to make the git add man page more accessible to Git\nusers who are less familiar with git jargon like \"working tree\" or \"index\"\nwhile communicating the same information for advanced users.\n\nSome notes:\n\n 1. I'm not sure about the SYNOPSIS changes, it seems useful to have a\n reminder near the top of what some commonly used options are, like\n [--patch | -p] but also I find listing all of the options at the\n beginning really distracts me from the command's core syntax.\n 2. I know there's a longstanding discussion about the use of the terms\n \"index\", \"cache\" and \"staging area\". I've tried to address that as best\n as I could.\n\nJulia Evans (5):\n doc: git-add: remove options from SYNOPSIS\n doc: git-add: start man page with an example\n doc: git-add: simplify discussion of ignored files\n doc: git-add: make explanation less dry\n doc: git-add: explain inconsistent terminology\n\n Documentation/git-add.adoc | 72 +++++++++++++++++++-------------------\n 1 file changed, 36 insertions(+), 36 deletions(-)\n\n\nbase-commit: 2c2ba49d55ff26c1082b8137b1ec5eeccb4337d1\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1952%2Fjvns%2Fclarify-add-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1952/jvns/clarify-add-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1952\n-- \ngitgitgadget\n"},{"id":"524084","messageId":"3a2cc38b72fb0f6ccc0ec9cbefadb7576cd8b934.1755029249.git.gitgitgadget@gmail.com","threadId":"63947","inReplyTo":"pull.1952.git.1755029249.gitgitgadget@gmail.com","subject":"[PATCH 1/5] doc: git-add: remove options from SYNOPSIS","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-12T20:07:25Z","receivedAt":"2025-08-12T20:07:33Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\nMotivations for this change:\n\n1. Listing a huge number of options is visually overwhelming when\n opening a man page for an unfamiliar command. It makes it harder\n to understand the command's core syntax, like `git add `\n2. For options which can be passed independently of any other options,\n including them in the SYNOPSIS does not add any information which you\n can't already get from reading the OPTIONS section. `git add` has\n some mutually exclusive options, namely:\n [--[no-]all | -A | --[no-]ignore-removal | [--update | -u]]\n but personally I already find that line so hard to parse that\n removing it doesn't remove a lot of information\n3. Some man pages already take this approach, like `git rebase` and\n `git status`\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-add.adoc | 6 +-----\n 1 file changed, 1 insertion(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc\nindex b7a735824d6c..12afeead6637 100644\n--- a/Documentation/git-add.adoc\n+++ b/Documentation/git-add.adoc\n@@ -8,11 +8,7 @@ git-add - Add file contents to the index\n SYNOPSIS\n --------\n [synopsis]\n-git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p]\n-\t[--edit | -e] [--[no-]all | -A | --[no-]ignore-removal | [--update | -u]] [--sparse]\n-\t[--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--renormalize]\n-\t[--chmod=(+|-)x] [--pathspec-from-file= [--pathspec-file-nul]]\n-\t[--] [...]\n+git add [] [--] [...]\n \n DESCRIPTION\n -----------\n-- \ngitgitgadget\n\n"},{"id":"524085","messageId":"310d2c1d8f7f68ae52ddd29f0ccb0a0364aba1a2.1755029249.git.gitgitgadget@gmail.com","threadId":"63947","inReplyTo":"pull.1952.git.1755029249.gitgitgadget@gmail.com","subject":"[PATCH 2/5] doc: git-add: start man page with an example","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-12T20:07:26Z","receivedAt":"2025-08-12T20:07:33Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\n- Replace the intro paragraph of the `git-add` man page with an\n example to try to clarify it for new users. The goal here is use less\n jargon but communicate essentially the same information.\n- Give an example of how to add only part of the changes to the file\n- Remove the snapshot-based explanation of the index and replace it with\n a diff-based explanation because I don't feel that it's useful in this\n context to emphasize that git uses a snapshot-based model: the main\n way most git users interact with the index is through `git diff` or\n `git status`, which is a completely diff-based view of the index.\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-add.adoc | 31 ++++++++++++++-----------------\n 1 file changed, 14 insertions(+), 17 deletions(-)\n\ndiff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc\nindex 12afeead6637..99ca2d0f7e21 100644\n--- a/Documentation/git-add.adoc\n+++ b/Documentation/git-add.adoc\n@@ -3,7 +3,7 @@ git-add(1)\n \n NAME\n ----\n-git-add - Add file contents to the index\n+git-add - Add new or changed files to the index\n \n SYNOPSIS\n --------\n@@ -12,18 +12,19 @@ git add [] [--] [...]\n \n DESCRIPTION\n -----------\n-This command updates the index using the current content found in\n-the working tree, to prepare the content staged for the next commit.\n-It typically adds the current content of existing paths as a whole,\n-but with some options it can also be used to add content with\n-only part of the changes made to the working tree files applied, or\n-remove paths that do not exist in the working tree anymore.\n-\n-The \"index\" holds a snapshot of the content of the working tree, and it\n-is this snapshot that is taken as the contents of the next commit. Thus\n-after making any changes to the working tree, and before running\n-the commit command, you must use the `add` command to add any new or\n-modified files to the index.\n+Add new or changed files to the index (also known as \"staging area\") to\n+prepare for a commit.\n+\n+By default, `git commit` only commits changes that you've added to the\n+index. For example, if you've edited `file.c` and want to commit your\n+changes, you can run:\n+\n+ git add file.c\n+ git commit\n+\n+You can also add only part of your changes to a file with `git add -p`.\n+Please see linkgit:git-commit[1] for alternative ways to add content to\n+a commit.\n \n This command can be performed multiple times before a commit. It only\n adds the content of the specified file(s) at the time the add command is\n@@ -40,10 +41,6 @@ directory recursion or filename globbing performed by Git (quote your\n globs before the shell) will be silently ignored. The `git add` command can\n be used to add ignored files with the `-f` (force) option.\n \n-Please see linkgit:git-commit[1] for alternative ways to add content to a\n-commit.\n-\n-\n OPTIONS\n -------\n `...`::\n-- \ngitgitgadget\n\n"},{"id":"524086","messageId":"3f4ab6150692418757c84db64cf6d3d79a654453.1755029249.git.gitgitgadget@gmail.com","threadId":"63947","inReplyTo":"pull.1952.git.1755029249.gitgitgadget@gmail.com","subject":"[PATCH 3/5] doc: git-add: simplify discussion of ignored files","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-12T20:07:27Z","receivedAt":"2025-08-12T20:07:34Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\n- Mention the --force option earlier\n- Remove the explanation of shell globbing vs git's internal glob\n system, it's a common gotcha but I don't think this is an appropriate\n place to explain that concept. There's some discussion of the gotchas\n around globbing and `git add` in the EXAMPLES section which I think\n is clearer.\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-add.adoc | 11 +++++------\n 1 file changed, 5 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc\nindex 99ca2d0f7e21..0c4ca1794c91 100644\n--- a/Documentation/git-add.adoc\n+++ b/Documentation/git-add.adoc\n@@ -34,12 +34,11 @@ you must run `git add` again to add the new content to the index.\n The `git status` command can be used to obtain a summary of which\n files have changes that are staged for the next commit.\n \n-The `git add` command will not add ignored files by default. If any\n-ignored files were explicitly specified on the command line, `git add`\n-will fail with a list of ignored files. Ignored files reached by\n-directory recursion or filename globbing performed by Git (quote your\n-globs before the shell) will be silently ignored. The `git add` command can\n-be used to add ignored files with the `-f` (force) option.\n+`git add` will not add ignored files by default. You can use the\n+`--force` option to add ignored files. If you explicitly specify the\n+exact filename of an ignored file (e.g. `git add ignored.txt`), `git\n+add` will fail with a list of ignored files. Otherwise it will silently\n+ignore the file.\n \n OPTIONS\n -------\n-- \ngitgitgadget\n\n"},{"id":"524087","messageId":"34b09deb61abfee8146cbbd6e1583c1c43fda197.1755029249.git.gitgitgadget@gmail.com","threadId":"63947","inReplyTo":"pull.1952.git.1755029249.gitgitgadget@gmail.com","subject":"[PATCH 4/5] doc: git-add: make explanation less dry","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-12T20:07:28Z","receivedAt":"2025-08-12T20:07:35Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\n- use examples\n- mention `git diff --staged`\n- link to git diff man page\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-add.adoc | 13 +++++++------\n 1 file changed, 7 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc\nindex 0c4ca1794c91..77cadbfee8e3 100644\n--- a/Documentation/git-add.adoc\n+++ b/Documentation/git-add.adoc\n@@ -26,13 +26,13 @@ You can also add only part of your changes to a file with `git add -p`.\n Please see linkgit:git-commit[1] for alternative ways to add content to\n a commit.\n \n-This command can be performed multiple times before a commit. It only\n-adds the content of the specified file(s) at the time the add command is\n-run; if you want subsequent changes included in the next commit, then\n-you must run `git add` again to add the new content to the index.\n+`git add` only adds the changes at the time that you run it. If you edit\n+`file.c` after adding it, you need to run `git add file.c` again before\n+committing.\n \n-The `git status` command can be used to obtain a summary of which\n-files have changes that are staged for the next commit.\n+If you want to check which changes have been added, you can run\n+`git status` to print out a summary of the changes that will be committed\n+or run `git diff --staged` to see the full diff.\n \n `git add` will not add ignored files by default. You can use the\n `--force` option to add ignored files. If you explicitly specify the\n@@ -443,6 +443,7 @@ linkgit:git-rm[1]\n linkgit:git-reset[1]\n linkgit:git-mv[1]\n linkgit:git-commit[1]\n+linkgit:git-diff[1]\n linkgit:git-update-index[1]\n \n GIT\n-- \ngitgitgadget\n\n"},{"id":"524088","messageId":"f7e8e4c63a1205740c2d54368d7bcdd686882680.1755029249.git.gitgitgadget@gmail.com","threadId":"63947","inReplyTo":"pull.1952.git.1755029249.gitgitgadget@gmail.com","subject":"[PATCH 5/5] doc: git-add: explain inconsistent terminology","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-12T20:07:29Z","receivedAt":"2025-08-12T20:07:36Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\nI think the fact that git uses these three terms interchangeably is\nextremely confusing and that it deserves to be noted.\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-add.adoc | 7 +++++++\n 1 file changed, 7 insertions(+)\n\ndiff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc\nindex 77cadbfee8e3..084342155f8b 100644\n--- a/Documentation/git-add.adoc\n+++ b/Documentation/git-add.adoc\n@@ -40,6 +40,13 @@ exact filename of an ignored file (e.g. `git add ignored.txt`), `git\n add` will fail with a list of ignored files. Otherwise it will silently\n ignore the file.\n \n+TERMINOLOGY NOTE\n+----------------\n+\n+Git uses the terms \"staging area\", \"index\" and \"cache\" interchangeably\n+for historical reasons. Many commands have flags like `--staged`,\n+`--index`, or `--cached`, and they all refer to the index.\n+\n OPTIONS\n -------\n `...`::\n-- \ngitgitgadget\n"},{"id":"524089","messageId":"xmqqms84s276.fsf@gitster.g","threadId":"63947","inReplyTo":"3a2cc38b72fb0f6ccc0ec9cbefadb7576cd8b934.1755029249.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 1/5] doc: git-add: remove options from SYNOPSIS","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-12T20:41:01Z","receivedAt":"2025-08-12T20:41:04Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" writes:\n\n> From: Julia Evans \n>\n> Motivations for this change:\n>\n> 1. Listing a huge number of options is visually overwhelming when\n> opening a man page for an unfamiliar command. It makes it harder\n> to understand the command's core syntax, like `git add `\n\nFor \"git add\", which has only one mode of operation, this may be\ngood.\n\nNote that in general this is not necessarily a good idea, when a\ncommand works in different modes (like \"git branch\" that can\nlist/enumerate or create/delete/manipulate), as not all the options\ncan be used in all the modes the command supports. The \"usage\" part\nof the output from \"git branch -h\" hits a good balance, and may want\nto use as a model.\n\nThere is t0450 that aspires to ensure the short usage \"git -h\"\nmatches the synopsis section of \"git help \" for all ; right\nnow we have too many exceptions, and we should move towards making\nthese exceptions smaller.\n\n> 2. For options which can be passed independently of any other options,\n> including them in the SYNOPSIS does not add any information which you\n> can't already get from reading the OPTIONS section.\n\nExcept that you have to scan a lot of text, which is quite\ninefficient when you *know* the general idea behind the option you\nwant to use, and are only looking for the exact spelling of it (e.g.\n\"was it spelled --ignore-removed?\")\n\n> `git add` has\n> some mutually exclusive options, namely:\n> [--[no-]all | -A | --[no-]ignore-removal | [--update | -u]]\n> but personally I already find that line so hard to parse that\n> removing it doesn't remove a lot of information\n\nIt is a very good point why we may want to have these cues to\nexpress \"these go together\" (my earlier example of \"branch\") and\n\"only one of these is used\". I tend to agree with you that these\nare not necessarily very easy to read.\n\nWhile it is important to make it easier for new readers to learn, we\nshould also keep in mind that nobody remains to be a newbie forever.\n\n> [synopsis]\n> -git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p]\n> -\t[--edit | -e] [--[no-]all | -A | --[no-]ignore-removal | [--update | -u]] [--sparse]\n> -\t[--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--renormalize]\n> -\t[--chmod=(+|-)x] [--pathspec-from-file= [--pathspec-file-nul]]\n> -\t[--] [...]\n\nThis being a long single line and with redundant \"--long|-s\" may be\nmaking it unnecessarily ugly. Have you considered folding lines and\nsimplifying \"[--long | -s]\" into \"[-s]\" and see if it makes easier\nto follow? Documentation/git-commit.adoc may serve as a better\nmodel.\n\n> +git add [] [--] [...]\n> \n> DESCRIPTION\n> -----------\n"},{"id":"524090","messageId":"CAPx1GveEX_r8thqpux0jcbEsEyLpNOvRWEvogUp4m_cNC5=dbw@mail.gmail.com","threadId":"63947","inReplyTo":"f7e8e4c63a1205740c2d54368d7bcdd686882680.1755029249.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 5/5] doc: git-add: explain inconsistent terminology","fromName":"Chris Torek","fromEmail":"chris.torek@gmail.com","sentAt":"2025-08-12T20:51:20Z","receivedAt":"2025-08-12T20:51:34Z","isPatch":true,"sender":{"key":"chris.torek@gmail.com","avatar":"https://avatars.githubusercontent.com/u/16826774?v=4"},"body":"On Tue, Aug 12, 2025 at 1:35 PM Julia Evans via GitGitGadget\n wrote:\n> +TERMINOLOGY NOTE\n> +----------------\n> +\n> +Git uses the terms \"staging area\", \"index\" and \"cache\" interchangeably\n> +for historical reasons. Many commands have flags like `--staged`,\n> +`--index`, or `--cached`, and they all refer to the index.\n> +\n\nI think this is also a good idea. Unfortunately, `git apply` has two\ndifferent meanings for `--index` vs `--cached` (I believe it's the\n*only* exception to the \"means the same thing\" rule...).\n\nChris\n"},{"id":"524091","messageId":"xmqqbjoks19f.fsf@gitster.g","threadId":"63947","inReplyTo":"310d2c1d8f7f68ae52ddd29f0ccb0a0364aba1a2.1755029249.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 2/5] doc: git-add: start man page with an example","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-12T21:01:16Z","receivedAt":"2025-08-12T21:01:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" writes:\n\n> - Remove the snapshot-based explanation of the index and replace it with\n> a diff-based explanation because I don't feel that it's useful in this\n> context to emphasize that git uses a snapshot-based model: the main\n> way most git users interact with the index is through `git diff` or\n> `git status`, which is a completely diff-based view of the index.\n\nBut isn't it the source of the most end-user confusion that they\ncannot wean themselves off of the diff/patch worldview?\n\nHow would you explain what the users would see in their \"git diff\",\n\"git diff --cached\", and \"git commit\" after doing \"edit && add &&\nedit\", if you explain \"add\" to be storing the \"diff\" made by the\nfirst edit? Does their \"git diff\" after the second \"edit\" take that\npreviously stored \"diff\" and another \"diff\" made by the second\n\"edit\" and magically combine them together to present a single\n\"diff\"?\n\n> -git-add - Add file contents to the index\n> +git-add - Add new or changed files to the index\n\nIn other words, I do think \"new or changed\" is a good thing to say,\nbut the word \"contents\" is fundamental here. \"Add contents of new\nor changed files to the index\" would be good.\n\n> +Add new or changed files to the index (also known as \"staging area\") to\n> +prepare for a commit.\n\nOK, but saying \"files\" here adds another kind of confusion. What is\n\"added\" is not the fact that these paths are kept track of by Git.\nInstead we add the snapshot of the contents at the time of 'git add'.\n\nWouldn't \"add file X\" confuse folks who still remember how other\nSCMs before Git operated (i.e. \"file X is now known, so if I make\nfurther changes to X next 'commit' command will record it\") into\nthinking that Git would do the same?\n\n> +By default, `git commit` only commits changes that you've added to the\n> +index. For example, if you've edited `file.c` and want to commit your\n> +changes, you can run:\n> +\n> + git add file.c\n> + git commit\n\nWhat happens when you did \"edit && add && edit && add\"? It commits\nthe two changes you added to the index? I do not think it is\nproductive to hide the fact that you are preparing a snapshot of the\n\"next commit\" in the index (or \"staging the contents for the next\ncommit in the staging area\") with various forms \"git add\", including\n\"git add -p\".\n\nAnd to help form that mental model, it would help to avoid phrasing\n\"commit your changes\" (as if you are somehow dealing with \"diff/patch\")\nand instead saying \"commit the result of your changes\" (stressing\nthat the \"state\" matters), I would think.\n\nDe-stressing the fact that we are taking a snapshot should probably\nbe considered a documentation regression here. Thanks to \"git add\"\ntaking a snapshot, users can further make experimental changes in\nthe working tree files freely and then come back to the exact\ncontents back by checking the path out of the index with \"git\ncheckout -- \". Thanks to \"git commit\" taking a snapshot,\nusers can even go back to the last commit by taking the exact\ncontents back by checking the path out of the HEAD with \"git\ncheckout HEAD -- \".\n\nI'll stop here and let others express their opinions without further\ncommenting for now.\n\nThanks for working on these updates.\n\n"},{"id":"524093","messageId":"xmqqpld0ql2e.fsf@gitster.g","threadId":"63947","inReplyTo":"CAPx1GveEX_r8thqpux0jcbEsEyLpNOvRWEvogUp4m_cNC5=dbw@mail.gmail.com","subject":"Re: [PATCH 5/5] doc: git-add: explain inconsistent terminology","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-12T21:36:25Z","receivedAt":"2025-08-12T21:36:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Chris Torek writes:\n\n> On Tue, Aug 12, 2025 at 1:35 PM Julia Evans via GitGitGadget\n> wrote:\n>> +TERMINOLOGY NOTE\n>> +----------------\n>> +\n>> +Git uses the terms \"staging area\", \"index\" and \"cache\" interchangeably\n>> +for historical reasons. Many commands have flags like `--staged`,\n>> +`--index`, or `--cached`, and they all refer to the index.\n>> +\n>\n> I think this is also a good idea. Unfortunately, `git apply` has two\n> different meanings for `--index` vs `--cached` (I believe it's the\n> *only* exception to the \"means the same thing\" rule...).\n\nYes, I think the first sentence is an excellent addition, even\nthough I do not know if \"git add\" is the best place to teach it.\n\nHowever, it will be disservice to users to say \"they all refer to\nthe index\" here. Yes, it is technically correct that they all refer\nto the index, but that much any intelligent readers can infer after\nreading the first sentance that historically these three words were\nused to refer to the same \"index\". And what I think is bad in that\nsecond sentence is that it implies they may mean the same thing\nwithout saying that. It is perfectly fine to say that these three\nwords express some operation around the index (sometimes called the\nstaging area). It also is fine to say that \"--staged\" is sometimes\nused as synonym for `--cached`.\n\nBut at least `--cached` and `--index` mean quite different things.\n\nAs \"git help cli\" explains, an operation that can affect only the\nindex would use \"--cached\" and both the index and the working tree\nwould use \"--index\".\n\nIt may be that \"apply\" is currently the only exception (I did not\ncheck), but it certainly is not guaranteed to stay to be the only\nexception. If a command wants to work on both the contents in the\nindex and in the working tree, such a command is very much welcomed\nto use the option \"--index\" to trigger such a mode of operation.\n\nConclusion? I would rather see \"Many commands have ...\" sentence\nstruck out. After all, that does not need to be taught to those who\ncame here to learn about \"git add\".\n\nThanks.\n"},{"id":"524094","messageId":"152d47a3-7744-476a-8ab8-43b7b52b67ea@app.fastmail.com","threadId":"63947","inReplyTo":"xmqqbjoks19f.fsf@gitster.g","subject":"Re: [PATCH 2/5] doc: git-add: start man page with an example","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-08-12T21:40:19Z","receivedAt":"2025-08-12T21:40:41Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"> But isn't it the source of the most end-user confusion that they\n> cannot wean themselves off of the diff/patch worldview?\n\nTo me it feels very contextual! My impression is that what's important for Git\nusers is to be able to think about commits as diffs in some contexts, and as\nsnapshots in other contexts. For example with `git rebase` I'm usually thinking\nof my commits as diffs, but it's very helpful to me to think of a merge commit\nas a snapshot, because the merge commit does not have to be a \"combination\" of\nthe two sides of the merge, it can have arbitrary extra content.\n\n> Wouldn't \"add file X\" confuse folks who still remember how other\n> SCMs before Git operated (i.e. \"file X is now known, so if I make\n> further changes to X next 'commit' command will record it\") into\n> thinking that Git would do the same?\n\nThe point about Subversion is interesting: I would expect that most\npeople learning about Git's data model in 2025 have never used\nSubversion.\n\nSo while I think it's extremely important to make accurate statements\nwhile talking about Git (and I think it's very possible that this description\nis not accurate enough!), I do not think it's so important to specifically\ntarget misconceptions that users coming from Subversion/CVS\nmay have.\n\n>> +By default, `git commit` only commits changes that you've added to the\n>> +index. For example, if you've edited `file.c` and want to commit your\n>> +changes, you can run:\n>> +\n>> + git add file.c\n>> + git commit\n>\n> What happens when you did \"edit && add && edit && add\"? It commits\n> the two changes you added to the index? I do not think it is\n> productive to hide the fact that you are preparing a snapshot of the\n> \"next commit\" in the index (or \"staging the contents for the next\n> commit in the staging area\") with various forms \"git add\", including\n> \"git add -p\".\n\nIt could! It's easy for me to imagine a world where the index\nstores an ordered list of diffs, which are applied as patches in\nseries when I commit. I guess you'd need some sort of\npatch + patch + patch + diff workflow to generate the final diff,\nbut to me that doesn't feel so different from what Git is actually doing in\npractice.\n\nIn any case, I'll think more about whether I think this is really\nan accurate description. I'm always especially interested in the practical\nconsequences of having misconceptions about Git: for example (and maybe I'm\nconvincing myself to change my position here!) with `git mv` I think it can\nbecome relevant pretty quickly that commits are snapshots, because if\nyou move a file and edit it then Git can't always accurately guess that you\nintended to \"move\" the file rather than delete the file and create a new one.\n\nI'd like to be able to have a similarly practical example of why it's important\nto think of commits as snapshots in the context of `git add` but I haven't quite\nfound the right one yet. I've noticed that people will often sort of \"reject\"\ninformation that does not fit their mental models, and I think \"commits are\nsnapshots, this is important in this context because of\n\" is much more convincing than just\n\"commits are snapshots\".\n"},{"id":"524095","messageId":"93133935-648a-4333-9272-c8528085499a@app.fastmail.com","threadId":"63947","inReplyTo":"xmqqpld0ql2e.fsf@gitster.g","subject":"Re: [PATCH 5/5] doc: git-add: explain inconsistent terminology","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-08-12T21:43:19Z","receivedAt":"2025-08-12T21:43:41Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"That sounds good to me, I'll remove the second sentence.\n\nOn Tue, Aug 12, 2025, at 5:36 PM, Junio C Hamano wrote:\n> Chris Torek writes:\n>\n>> On Tue, Aug 12, 2025 at 1:35 PM Julia Evans via GitGitGadget\n>> wrote:\n>>> +TERMINOLOGY NOTE\n>>> +----------------\n>>> +\n>>> +Git uses the terms \"staging area\", \"index\" and \"cache\" interchangeably\n>>> +for historical reasons. Many commands have flags like `--staged`,\n>>> +`--index`, or `--cached`, and they all refer to the index.\n>>> +\n>>\n>> I think this is also a good idea. Unfortunately, `git apply` has two\n>> different meanings for `--index` vs `--cached` (I believe it's the\n>> *only* exception to the \"means the same thing\" rule...).\n>\n> Yes, I think the first sentence is an excellent addition, even\n> though I do not know if \"git add\" is the best place to teach it.\n>\n> However, it will be disservice to users to say \"they all refer to\n> the index\" here. Yes, it is technically correct that they all refer\n> to the index, but that much any intelligent readers can infer after\n> reading the first sentance that historically these three words were\n> used to refer to the same \"index\". And what I think is bad in that\n> second sentence is that it implies they may mean the same thing\n> without saying that. It is perfectly fine to say that these three\n> words express some operation around the index (sometimes called the\n> staging area). It also is fine to say that \"--staged\" is sometimes\n> used as synonym for `--cached`.\n>\n> But at least `--cached` and `--index` mean quite different things.\n>\n> As \"git help cli\" explains, an operation that can affect only the\n> index would use \"--cached\" and both the index and the working tree\n> would use \"--index\".\n>\n> It may be that \"apply\" is currently the only exception (I did not\n> check), but it certainly is not guaranteed to stay to be the only\n> exception. If a command wants to work on both the contents in the\n> index and in the working tree, such a command is very much welcomed\n> to use the option \"--index\" to trigger such a mode of operation.\n>\n> Conclusion? I would rather see \"Many commands have ...\" sentence\n> struck out. After all, that does not need to be taught to those who\n> came here to learn about \"git add\".\n>\n> Thanks.\n"},{"id":"524097","messageId":"xmqqwm78p4uh.fsf@gitster.g","threadId":"63947","inReplyTo":"152d47a3-7744-476a-8ab8-43b7b52b67ea@app.fastmail.com","subject":"Re: [PATCH 2/5] doc: git-add: start man page with an example","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-12T22:12:06Z","receivedAt":"2025-08-12T22:12:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" writes:\n\n>> Wouldn't \"add file X\" confuse folks who still remember how other\n>> SCMs before Git operated (i.e. \"file X is now known, so if I make\n>> further changes to X next 'commit' command will record it\") into\n>> thinking that Git would do the same?\n>\n> The point about Subversion is interesting: I would expect that most\n> people learning about Git's data model in 2025 have never used\n> Subversion.\n\nEven though I promised that I won't comment on this thread further\nfor now, I'd have to respond to this one. \n\nTimes change. I didn't have Subversion in mind when I wrote the\nabove. It was CVS ;-)\n\nYes, I have heard that for recent crop of developers especially\nnewgrads, Git is the only SCM they've ever touched. If we can\nassume that the data and mental model of Git is natural for our\nintended audiences, that is great (we can also forget about the\ndiff/patch based world view, which comes from how CVS/RCS stored\ntheir revision data, and assume that the snapshot based world view\nis natural to our readers).\n"},{"id":"524098","messageId":"4d922dbf-ad97-42da-be19-905de5bd18de@app.fastmail.com","threadId":"63947","inReplyTo":"xmqqwm78p4uh.fsf@gitster.g","subject":"Re: [PATCH 2/5] doc: git-add: start man page with an example","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-08-12T22:45:32Z","receivedAt":"2025-08-12T22:45:53Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"> Yes, I have heard that for recent crop of developers especially\n> newgrads, Git is the only SCM they've ever touched. If we can\n> assume that the data and mental model of Git is natural for our\n> intended audiences, that is great (we can also forget about the\n> diff/patch based world view, which comes from how CVS/RCS stored\n> their revision data, and assume that the snapshot based world view\n> is natural to our readers).\n\nGit is certainly the only version control system I've ever used: I started using\nit when I was a new grad 15 years ago. Everything I know about Subversion or CVS\n(almost nothing) I know from reading explanations of Git aimed at their users\nor from trying to understand the origin of some of Git's terminology choices :)\n\nre whether the snapshot based world view is \"natural\" or not to Git users: \nI did some very unscientific polls about people's mental models of Git\na while back at https://jvns.ca/blog/2024/03/28/git-poll-results/#commits\n\nThat one says that 42% of folks who responded think of commits as \"snapshots\"\nand 50% as \"diffs\", which feels encouraging to me: after all, the poll doesn't\nask how Git represents commits internally, and many people replied in the\ncomments to say that they think of commits in both ways depending on the\nsituation.\n"},{"id":"524135","messageId":"d027b0cc-a2b0-4b73-b7e0-410fc559fd51@app.fastmail.com","threadId":"63947","inReplyTo":"xmqqms84s276.fsf@gitster.g","subject":"Re: [PATCH 1/5] doc: git-add: remove options from SYNOPSIS","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-08-13T16:58:50Z","receivedAt":"2025-08-13T16:59:13Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"Thanks for the comments. I think for now I'll just remove this patch\nfrom the series since I don't see a clear way forward and I think it'll\nmake it easier to focus on the other changes.\n\n> Note that in general this is not necessarily a good idea, when a\n> command works in different modes (like \"git branch\" that can\n> list/enumerate or create/delete/manipulate), as not all the options\n> can be used in all the modes the command supports. \n\nI've been thinking about that as well: I have some ideas I've been working on\nfor how to clarify the usage of different \"modes\" of a command by giving the\nmodes names, will share those when I get to a command with modes.\n\n> Except that you have to scan a lot of text, which is quite\n> inefficient when you *know* the general idea behind the option you\n> want to use, and are only looking for the exact spelling of it (e.g.\n> \"was it spelled --ignore-removed?\")\n\nThat's fair. Something that I hadn't considered is that how easy the OPTIONS\nsection is to scan depends on how the man page is formatted: some man\npage viewers will bold the options (which I think makes them easier to scan),\nbut some won't.\n\n> While it is important to make it easier for new readers to learn, we\n> should also keep in mind that nobody remains to be a newbie forever.\n> Have you considered folding lines and\n> simplifying \"[--long | -s]\" into \"[-s]\" and see if it makes easier\n> to follow? Documentation/git-commit.adoc may serve as a better\n> model.\n\nHmm, here's what it looks like with the long options removed.\nTo me it doesn't feel like a big enough improvement, and it's harder\nto tell what some of the short options (like `-n`) mean.\n\ngit add [-p] [-v] [-n] [-f] [-i] [-e] [-A | --no-all | -u]\n\t[--sparse] [--intent-to-add | -N] [--refresh] [--ignore-errors]\n\t[--ignore-missing] [--renormalize] [--chmod=(+|-)x]\n\t[--pathspec-from-file= [--pathspec-file-nul]]\n\t[--] [...]\n"},{"id":"524138","messageId":"CALnO6CCjW=W4A7d4se8fCe7gzuDLc-SyGv7JbVqbtSSkSM1bNg@mail.gmail.com","threadId":"63947","inReplyTo":"152d47a3-7744-476a-8ab8-43b7b52b67ea@app.fastmail.com","subject":"Re: [PATCH 2/5] doc: git-add: start man page with an example","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-08-13T17:22:34Z","receivedAt":"2025-08-13T17:22:48Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Tue, Aug 12, 2025 at 5:40 PM Julia Evans wrote:\n>\n> > But isn't it the source of the most end-user confusion that they\n> > cannot wean themselves off of the diff/patch worldview?\n>\n> To me it feels very contextual! My impression is that what's important for Git\n> users is to be able to think about commits as diffs in some contexts, and as\n> snapshots in other contexts. For example with `git rebase` I'm usually thinking\n> of my commits as diffs, but it's very helpful to me to think of a merge commit\n> as a snapshot, because the merge commit does not have to be a \"combination\" of\n> the two sides of the merge, it can have arbitrary extra content.\n>\n[snip]\n>\n> >> +By default, `git commit` only commits changes that you've added to the\n> >> +index. For example, if you've edited `file.c` and want to commit your\n> >> +changes, you can run:\n> >> +\n> >> + git add file.c\n> >> + git commit\n> >\n> > What happens when you did \"edit && add && edit && add\"? It commits\n> > the two changes you added to the index? I do not think it is\n> > productive to hide the fact that you are preparing a snapshot of the\n> > \"next commit\" in the index (or \"staging the contents for the next\n> > commit in the staging area\") with various forms \"git add\", including\n> > \"git add -p\".\n>\n> It could! It's easy for me to imagine a world where the index\n> stores an ordered list of diffs, which are applied as patches in\n> series when I commit. I guess you'd need some sort of\n> patch + patch + patch + diff workflow to generate the final diff,\n> but to me that doesn't feel so different from what Git is actually doing in\n> practice.\n>\n> In any case, I'll think more about whether I think this is really\n> an accurate description. I'm always especially interested in the practical\n> consequences of having misconceptions about Git: for example (and maybe I'm\n> convincing myself to change my position here!) with `git mv` I think it can\n> become relevant pretty quickly that commits are snapshots, because if\n> you move a file and edit it then Git can't always accurately guess that you\n> intended to \"move\" the file rather than delete the file and create a new one.\n>\n> I'd like to be able to have a similarly practical example of why it's important\n> to think of commits as snapshots in the context of `git add` but I haven't quite\n> found the right one yet. I've noticed that people will often sort of \"reject\"\n> information that does not fit their mental models, and I think \"commits are\n> snapshots, this is important in this context because of\n> \" is much more convincing than just\n> \"commits are snapshots\".\n\nLess a comment on this patch or diff ;) and more a meta-note: I happen\nto have several links saved on the idea of \"Snapshot vs. Patch\" aka\n\"commit duality\", so I figured I'd share. They reinforce to me, at\nleast, that the contextual mode of thinking is useful in practice,\neven if the snapshot model is the (semantic) storage model [*].\nKnowing about snapshots does make it far easier to interact with\nobjects directly, which also frequently helps me better understand how\nto use particular commands.\n\n- https://www.thirtythreeforty.net/posts/2020/01/the-wave-particle-duality-of-git-commits/\n- https://roadrunnertwice.dreamwidth.org/596185.html (which references\nJulia's work)\n- of course, https://jvns.ca/blog/2024/01/05/do-we-think-of-git-commits-as-diffs--snapshots--or-histories/\n;)\n- https://stackoverflow.com/q/40617288/4400820,\nhttps://stackoverflow.com/q/73646342/4400820,\nhttps://stackoverflow.com/a/27760319/4400820\n- https://github.blog/open-source/git/commits-are-snapshots-not-diffs/\n- https://lore.kernel.org/git/alpine.LFD.0.98.0705090856220.4062@woody.linux-foundation.org/\n\nWhat I find is that, while we keep trying to reinforce the snapshot\nmentality, there are situations where thinking in diffs is a\nreasonable approximation. In the particular case of git-add, most\ninteractions I observe with the index are diff-based (git diff, git\ndiff --cached, etc.), but I'm not sure how to usefully clarify the\nrelationship between those things and the underlying trees involved\n(working tree, HEAD, index :0:) in a manual section targeted primarily\nat newcomers.\n\n[*]: \"Semantic\" because deltas in packfiles muddy the _actual_ storage\nmodel somewhat :)\n\n-- \nD. Ben Knoble\n"},{"id":"524139","messageId":"CALnO6CDpv_Mess+vmvrLFODZq2Ls-v92FEsoP02At+BP1tgXDQ@mail.gmail.com","threadId":"63947","inReplyTo":"3f4ab6150692418757c84db64cf6d3d79a654453.1755029249.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 3/5] doc: git-add: simplify discussion of ignored files","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-08-13T17:24:34Z","receivedAt":"2025-08-13T17:24:47Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Tue, Aug 12, 2025 at 4:10 PM Julia Evans via GitGitGadget\n wrote:\n>\n> From: Julia Evans \n>\n> - Mention the --force option earlier\n> - Remove the explanation of shell globbing vs git's internal glob\n> system, it's a common gotcha but I don't think this is an appropriate\n> place to explain that concept. There's some discussion of the gotchas\n> around globbing and `git add` in the EXAMPLES section which I think\n> is clearer.\n>\n> Signed-off-by: Julia Evans \n> ---\n> Documentation/git-add.adoc | 11 +++++------\n> 1 file changed, 5 insertions(+), 6 deletions(-)\n>\n> diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc\n> index 99ca2d0f7e21..0c4ca1794c91 100644\n> --- a/Documentation/git-add.adoc\n> +++ b/Documentation/git-add.adoc\n> @@ -34,12 +34,11 @@ you must run `git add` again to add the new content to the index.\n> The `git status` command can be used to obtain a summary of which\n> files have changes that are staged for the next commit.\n>\n> -The `git add` command will not add ignored files by default. If any\n> -ignored files were explicitly specified on the command line, `git add`\n> -will fail with a list of ignored files. Ignored files reached by\n> -directory recursion or filename globbing performed by Git (quote your\n> -globs before the shell) will be silently ignored. The `git add` command can\n> -be used to add ignored files with the `-f` (force) option.\n> +`git add` will not add ignored files by default. You can use the\n> +`--force` option to add ignored files. If you explicitly specify the\n> +exact filename of an ignored file (e.g. `git add ignored.txt`), `git\n> +add` will fail with a list of ignored files. Otherwise it will silently\n> +ignore the file.\n\nThis reads more clearly to me, although I think it's worth trying to\nkeep the style \"The `git add` command\" command to avoid strange\npunctuation/capitalization at the start of a sentence.\n\nThanks for working on these :)\n\n-- \nD. Ben Knoble\n"},{"id":"524151","messageId":"2319022.iZASKD2KPV@cayenne","threadId":"63947","inReplyTo":"3a2cc38b72fb0f6ccc0ec9cbefadb7576cd8b934.1755029249.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 1/5] doc: git-add: remove options from SYNOPSIS","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2025-08-13T20:47:36Z","receivedAt":"2025-08-13T20:47:53Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On Tuesday, 12 August 2025 22:07:25 CEST Julia Evans via GitGitGadget wrote:\n> From: Julia Evans \n> \n> Motivations for this change:\n> \n> 1. Listing a huge number of options is visually overwhelming when\n> opening a man page for an unfamiliar command. It makes it harder\n> to understand the command's core syntax, like `git add `\n> 2. For options which can be passed independently of any other options,\n> including them in the SYNOPSIS does not add any information which you\n> can't already get from reading the OPTIONS section. `git add` has\n> some mutually exclusive options, namely:\n> [--[no-]all | -A | --[no-]ignore-removal | [--update | -u]]\n> but personally I already find that line so hard to parse that\n> removing it doesn't remove a lot of information\n> 3. Some man pages already take this approach, like `git rebase` and\n> `git status`\n> \n> Signed-off-by: Julia Evans \n> ---\n> Documentation/git-add.adoc | 6 +-----\n> 1 file changed, 1 insertion(+), 5 deletions(-)\n> \n> diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc\n> index b7a735824d6c..12afeead6637 100644\n> --- a/Documentation/git-add.adoc\n> +++ b/Documentation/git-add.adoc\n> @@ -8,11 +8,7 @@ git-add - Add file contents to the index\n> SYNOPSIS\n> --------\n> [synopsis]\n> -git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -\ni]\n> [--patch | -p] -\t[--edit | -e] [--[no-]all | -A | --[no-]ignore-removal |\n> [--update | -u]] [--sparse] -\t[--intent-to-add | -N] [--refresh] [--\nignore-errors]\n> [--ignore-missing] [--renormalize] -\t[--chmod=(+|-)x] [--pathspec-from-\nfile=\n> [--pathspec-file-nul]]\n> -\t[--] [...]\n> +git add [] [--] [...]\n> \n> DESCRIPTION\n> -----------\n\n\nHello,\n\nI'm not crazy about this change. In its new form, it is almost useless and \nformally wrong: according to it, `git add` is a valid invocation. The question \nis about how this synopsis section is supposed to be used. For me, this is a \nquick refresher of the available options, their exact name and how they can be \ncombined, a kind of compact overview.\n\nI'm not saying that the current form is good. For instance, I would expect to \nsee alternative forms such as `git add -u` appear on their own line whereas \nother forms require . There are common options that could be hidden \ninto the [] stuff, even if it kills a bit the \"compact summary\" \nfeature of the synopsis, but as you said, these are independent and can be \nfound under the 'OPTIONS' section.\n\nThe design of the man pages predates some more modern approaches to organizing \ntechnical documentation e.g. https://diataxis.fr/ and https://help.adobe.com/\nen_US/framemaker/2019/using/using-framemaker-2019/user-guide/\nfrm_structauthdita_sd_dita-topics.html. Thus they are mixing different aims/\napproaches in a single document. Anyway, we can agree to classify some of the \nmanual page sections into the more modern typing. For instance, I think \nSYNOPSIS falls under the \"reference\" type, and as such should be as \ncomprehensive as possible.\n\nJean-Noël\n\n\n\n"},{"id":"524158","messageId":"pull.1952.v2.git.1755127218.gitgitgadget@gmail.com","threadId":"63947","inReplyTo":"pull.1952.git.1755029249.gitgitgadget@gmail.com","subject":"[PATCH v2 0/4] doc: git-add: clarify DESCRIPTION section","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-13T23:20:14Z","receivedAt":"2025-08-13T23:20:22Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":" * Remove changes to SYNOPSIS\n * Add a sentence describing what \"the index\" is.\n * Shorten the terminology note\n * Say \"The git add command\" instead of git add\n\nJulia Evans (4):\n doc: git-add: start man page with an example\n doc: git-add: simplify discussion of ignored files\n doc: git-add: make explanation less dry\n doc: git-add: explain inconsistent terminology\n\n Documentation/git-add.adoc | 64 ++++++++++++++++++++------------------\n 1 file changed, 33 insertions(+), 31 deletions(-)\n\n\nbase-commit: 2c2ba49d55ff26c1082b8137b1ec5eeccb4337d1\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1952%2Fjvns%2Fclarify-add-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1952/jvns/clarify-add-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/1952\n\nRange-diff vs v1:\n\n 1: 3a2cc38b72f < -: ----------- doc: git-add: remove options from SYNOPSIS\n 2: 310d2c1d8f7 ! 1: d041d09589b doc: git-add: start man page with an example\n @@ Documentation/git-add.adoc: git-add(1)\n \n SYNOPSIS\n --------\n -@@ Documentation/git-add.adoc: git add [] [--] [...]\n +@@ Documentation/git-add.adoc: git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [-\n \n DESCRIPTION\n -----------\n @@ Documentation/git-add.adoc: git add [] [--] [...]\n -after making any changes to the working tree, and before running\n -the commit command, you must use the `add` command to add any new or\n -modified files to the index.\n -+Add new or changed files to the index (also known as \"staging area\") to\n -+prepare for a commit.\n ++Add new or changed files to the index to prepare for a commit. The\n ++\"index\" (also known as \"staging area\") is where Git stores the changes\n ++that will be in the next commit.\n +\n +By default, `git commit` only commits changes that you've added to the\n +index. For example, if you've edited `file.c` and want to commit your\n 3: 3f4ab615069 = 2: 63c9e0361dc doc: git-add: simplify discussion of ignored files\n 4: 34b09deb61a ! 3: ce1eafb0286 doc: git-add: make explanation less dry\n @@ Documentation/git-add.adoc: You can also add only part of your changes to a file\n -adds the content of the specified file(s) at the time the add command is\n -run; if you want subsequent changes included in the next commit, then\n -you must run `git add` again to add the new content to the index.\n -+`git add` only adds the changes at the time that you run it. If you edit\n -+`file.c` after adding it, you need to run `git add file.c` again before\n -+committing.\n ++The `git add` command only adds the changes at the time that you run it.\n ++If you edit `file.c` after adding it, you need to run `git add file.c`\n ++again before committing.\n \n -The `git status` command can be used to obtain a summary of which\n -files have changes that are staged for the next commit.\n 5: f7e8e4c63a1 ! 4: 9e595f9ad59 doc: git-add: explain inconsistent terminology\n @@ Documentation/git-add.adoc: exact filename of an ignored file (e.g. `git add ign\n add` will fail with a list of ignored files. Otherwise it will silently\n ignore the file.\n \n -+TERMINOLOGY NOTE\n -+----------------\n -+\n ++[NOTE]\n +Git uses the terms \"staging area\", \"index\" and \"cache\" interchangeably\n -+for historical reasons. Many commands have flags like `--staged`,\n -+`--index`, or `--cached`, and they all refer to the index.\n ++for historical reasons.\n +\n OPTIONS\n -------\n\n-- \ngitgitgadget\n"},{"id":"524159","messageId":"d041d09589b51734a8cc257f80cdaf210c6676e7.1755127218.git.gitgitgadget@gmail.com","threadId":"63947","inReplyTo":"pull.1952.v2.git.1755127218.gitgitgadget@gmail.com","subject":"[PATCH v2 1/4] doc: git-add: start man page with an example","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-13T23:20:15Z","receivedAt":"2025-08-13T23:20:23Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\n- Replace the intro paragraph of the `git-add` man page with an\n example to try to clarify it for new users. The goal here is use less\n jargon but communicate essentially the same information.\n- Give an example of how to add only part of the changes to the file\n- Remove the snapshot-based explanation of the index and replace it with\n a diff-based explanation because I don't feel that it's useful in this\n context to emphasize that git uses a snapshot-based model: the main\n way most git users interact with the index is through `git diff` or\n `git status`, which is a completely diff-based view of the index.\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-add.adoc | 32 +++++++++++++++-----------------\n 1 file changed, 15 insertions(+), 17 deletions(-)\n\ndiff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc\nindex b7a735824d6c..949b016e6fa2 100644\n--- a/Documentation/git-add.adoc\n+++ b/Documentation/git-add.adoc\n@@ -3,7 +3,7 @@ git-add(1)\n \n NAME\n ----\n-git-add - Add file contents to the index\n+git-add - Add new or changed files to the index\n \n SYNOPSIS\n --------\n@@ -16,18 +16,20 @@ git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [-\n \n DESCRIPTION\n -----------\n-This command updates the index using the current content found in\n-the working tree, to prepare the content staged for the next commit.\n-It typically adds the current content of existing paths as a whole,\n-but with some options it can also be used to add content with\n-only part of the changes made to the working tree files applied, or\n-remove paths that do not exist in the working tree anymore.\n-\n-The \"index\" holds a snapshot of the content of the working tree, and it\n-is this snapshot that is taken as the contents of the next commit. Thus\n-after making any changes to the working tree, and before running\n-the commit command, you must use the `add` command to add any new or\n-modified files to the index.\n+Add new or changed files to the index to prepare for a commit. The\n+\"index\" (also known as \"staging area\") is where Git stores the changes\n+that will be in the next commit.\n+\n+By default, `git commit` only commits changes that you've added to the\n+index. For example, if you've edited `file.c` and want to commit your\n+changes, you can run:\n+\n+ git add file.c\n+ git commit\n+\n+You can also add only part of your changes to a file with `git add -p`.\n+Please see linkgit:git-commit[1] for alternative ways to add content to\n+a commit.\n \n This command can be performed multiple times before a commit. It only\n adds the content of the specified file(s) at the time the add command is\n@@ -44,10 +46,6 @@ directory recursion or filename globbing performed by Git (quote your\n globs before the shell) will be silently ignored. The `git add` command can\n be used to add ignored files with the `-f` (force) option.\n \n-Please see linkgit:git-commit[1] for alternative ways to add content to a\n-commit.\n-\n-\n OPTIONS\n -------\n `...`::\n-- \ngitgitgadget\n\n"},{"id":"524160","messageId":"63c9e0361dc02c15afeea3cad1656e1631637f60.1755127218.git.gitgitgadget@gmail.com","threadId":"63947","inReplyTo":"pull.1952.v2.git.1755127218.gitgitgadget@gmail.com","subject":"[PATCH v2 2/4] doc: git-add: simplify discussion of ignored files","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-13T23:20:16Z","receivedAt":"2025-08-13T23:20:23Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\n- Mention the --force option earlier\n- Remove the explanation of shell globbing vs git's internal glob\n system, it's a common gotcha but I don't think this is an appropriate\n place to explain that concept. There's some discussion of the gotchas\n around globbing and `git add` in the EXAMPLES section which I think\n is clearer.\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-add.adoc | 11 +++++------\n 1 file changed, 5 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc\nindex 949b016e6fa2..75e223f6b1ea 100644\n--- a/Documentation/git-add.adoc\n+++ b/Documentation/git-add.adoc\n@@ -39,12 +39,11 @@ you must run `git add` again to add the new content to the index.\n The `git status` command can be used to obtain a summary of which\n files have changes that are staged for the next commit.\n \n-The `git add` command will not add ignored files by default. If any\n-ignored files were explicitly specified on the command line, `git add`\n-will fail with a list of ignored files. Ignored files reached by\n-directory recursion or filename globbing performed by Git (quote your\n-globs before the shell) will be silently ignored. The `git add` command can\n-be used to add ignored files with the `-f` (force) option.\n+`git add` will not add ignored files by default. You can use the\n+`--force` option to add ignored files. If you explicitly specify the\n+exact filename of an ignored file (e.g. `git add ignored.txt`), `git\n+add` will fail with a list of ignored files. Otherwise it will silently\n+ignore the file.\n \n OPTIONS\n -------\n-- \ngitgitgadget\n\n"},{"id":"524161","messageId":"ce1eafb02860b390da9359f92fcf098b7cdd3a94.1755127218.git.gitgitgadget@gmail.com","threadId":"63947","inReplyTo":"pull.1952.v2.git.1755127218.gitgitgadget@gmail.com","subject":"[PATCH v2 3/4] doc: git-add: make explanation less dry","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-13T23:20:17Z","receivedAt":"2025-08-13T23:20:24Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\n- use examples\n- mention `git diff --staged`\n- link to git diff man page\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-add.adoc | 13 +++++++------\n 1 file changed, 7 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc\nindex 75e223f6b1ea..6a6f5223419f 100644\n--- a/Documentation/git-add.adoc\n+++ b/Documentation/git-add.adoc\n@@ -31,13 +31,13 @@ You can also add only part of your changes to a file with `git add -p`.\n Please see linkgit:git-commit[1] for alternative ways to add content to\n a commit.\n \n-This command can be performed multiple times before a commit. It only\n-adds the content of the specified file(s) at the time the add command is\n-run; if you want subsequent changes included in the next commit, then\n-you must run `git add` again to add the new content to the index.\n+The `git add` command only adds the changes at the time that you run it.\n+If you edit `file.c` after adding it, you need to run `git add file.c`\n+again before committing.\n \n-The `git status` command can be used to obtain a summary of which\n-files have changes that are staged for the next commit.\n+If you want to check which changes have been added, you can run\n+`git status` to print out a summary of the changes that will be committed\n+or run `git diff --staged` to see the full diff.\n \n `git add` will not add ignored files by default. You can use the\n `--force` option to add ignored files. If you explicitly specify the\n@@ -448,6 +448,7 @@ linkgit:git-rm[1]\n linkgit:git-reset[1]\n linkgit:git-mv[1]\n linkgit:git-commit[1]\n+linkgit:git-diff[1]\n linkgit:git-update-index[1]\n \n GIT\n-- \ngitgitgadget\n\n"},{"id":"524162","messageId":"9e595f9ad59776d74a431731824410c7b73795dd.1755127218.git.gitgitgadget@gmail.com","threadId":"63947","inReplyTo":"pull.1952.v2.git.1755127218.gitgitgadget@gmail.com","subject":"[PATCH v2 4/4] doc: git-add: explain inconsistent terminology","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-13T23:20:18Z","receivedAt":"2025-08-13T23:20:25Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\nI think the fact that git uses these three terms interchangeably is\nextremely confusing and that it deserves to be noted.\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-add.adoc | 4 ++++\n 1 file changed, 4 insertions(+)\n\ndiff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc\nindex 6a6f5223419f..0b887e1d60ca 100644\n--- a/Documentation/git-add.adoc\n+++ b/Documentation/git-add.adoc\n@@ -45,6 +45,10 @@ exact filename of an ignored file (e.g. `git add ignored.txt`), `git\n add` will fail with a list of ignored files. Otherwise it will silently\n ignore the file.\n \n+[NOTE]\n+Git uses the terms \"staging area\", \"index\" and \"cache\" interchangeably\n+for historical reasons.\n+\n OPTIONS\n -------\n `...`::\n-- \ngitgitgadget\n"},{"id":"524163","messageId":"xmqq4iuabup7.fsf@gitster.g","threadId":"63947","inReplyTo":"152d47a3-7744-476a-8ab8-43b7b52b67ea@app.fastmail.com","subject":"Re: [PATCH 2/5] doc: git-add: start man page with an example","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-14T00:41:56Z","receivedAt":"2025-08-14T00:41:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" writes:\n\n> an accurate description. I'm always especially interested in the practical\n> consequences of having misconceptions about Git: for example (and maybe I'm\n> convincing myself to change my position here!) with `git mv` I think it can\n> become relevant pretty quickly that commits are snapshots, because if\n> you move a file and edit it then Git can't always accurately guess that you\n> intended to \"move\" the file rather than delete the file and create a new one.\n\nThere is an easier-to-understand example. If you pretend that you\n\"add\" series of \"diff/patch\" to the index as you repeat \"edit &&\nadd\" three times, in the mental model of the users, there would be\nthree set of patches stored in the index somehow. It would be a\nfair wish for the users to have to be able to revert only the change\nyou added with your second \"git add\" while keeping the first one and\nthe third (latest) one. You cannot explain why you fundamentally\ncannot give them such a new \"feature\", until you admit that what is\nrecorded is the latest snapshot and earlier snapshots are discarded.\n\nAnother thing that the \"collection of diff/patch\" view probably\nharms understanding of users is merge, which is not a set of diffs,\none for each parent and the merge result. Of course, as a merge is\nsymmetric across the parents, it is not diff between the first\nparent and the merge result, either.\n"},{"id":"524164","messageId":"CALnO6CA2bv0CHcEW-n=VU0xZXHgSrpXV_Dc3Q+HAGV7=Mr-_8Q@mail.gmail.com","threadId":"63947","inReplyTo":"63c9e0361dc02c15afeea3cad1656e1631637f60.1755127218.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 2/4] doc: git-add: simplify discussion of ignored files","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-08-14T00:59:54Z","receivedAt":"2025-08-14T01:00:09Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Wed, Aug 13, 2025 at 7:20 PM Julia Evans via GitGitGadget\n wrote:\n>\n> From: Julia Evans \n>\n> - Mention the --force option earlier\n> - Remove the explanation of shell globbing vs git's internal glob\n> system, it's a common gotcha but I don't think this is an appropriate\n> place to explain that concept. There's some discussion of the gotchas\n> around globbing and `git add` in the EXAMPLES section which I think\n> is clearer.\n>\n> Signed-off-by: Julia Evans \n> ---\n> Documentation/git-add.adoc | 11 +++++------\n> 1 file changed, 5 insertions(+), 6 deletions(-)\n>\n> diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc\n> index 949b016e6fa2..75e223f6b1ea 100644\n> --- a/Documentation/git-add.adoc\n> +++ b/Documentation/git-add.adoc\n> @@ -39,12 +39,11 @@ you must run `git add` again to add the new content to the index.\n> The `git status` command can be used to obtain a summary of which\n> files have changes that are staged for the next commit.\n>\n> -The `git add` command will not add ignored files by default. If any\n> -ignored files were explicitly specified on the command line, `git add`\n> -will fail with a list of ignored files. Ignored files reached by\n> -directory recursion or filename globbing performed by Git (quote your\n> -globs before the shell) will be silently ignored. The `git add` command can\n> -be used to add ignored files with the `-f` (force) option.\n> +`git add` will not add ignored files by default. You can use the\n\nNot worth a re-roll on its own, but this is another instance where\nstarting a sentence with `git add` seems odd to me.\n\nThe range-diff in v2 looked good to me overall.\n\n-- \nD. Ben Knoble\n"},{"id":"524167","messageId":"e1c9f388-f72c-4bb4-b05d-b5b183501456@app.fastmail.com","threadId":"63947","inReplyTo":"xmqq4iuabup7.fsf@gitster.g","subject":"Re: [PATCH 2/5] doc: git-add: start man page with an example","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-08-14T02:59:18Z","receivedAt":"2025-08-14T03:00:17Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"> There is an easier-to-understand example. If you pretend that you\n> \"add\" series of \"diff/patch\" to the index as you repeat \"edit &&\n> add\" three times, in the mental model of the users, there would be\n> three set of patches stored in the index somehow. It would be a\n> fair wish for the users to have to be able to revert only the change\n> you added with your second \"git add\" while keeping the first one and\n> the third (latest) one. You cannot explain why you fundamentally\n> cannot give them such a new \"feature\", until you admit that what is\n> recorded is the latest snapshot and earlier snapshots are discarded.\n\nThanks, I think this is the perfect example and it gets at something about git\nadd that i’ve never totally understood: why are the earlier snapshots discarded?\n\nNaively, one might think that:\n\n1. the git index is just a tree object\n2. when you commit, Git takes that tree object, attaches a\n message, and makes a commit with it\n3. git maintains some sort of history (like the reflog) for the past \"index\"\n tree objects\n\nIf Git worked that way, I imagine it would be possible to implement the feature\nyou describe, and I feel like there's some sort of obvious reason (something\nto do with performance?) for why the index isn't implemented this way that\nI've never learned.\n\nThis example makes me think that if we want people to understand the\nlimitations of the index, it's important to communicate that the past\nindex snapshots are *discarded* and not just that the index is a snapshot.\n"},{"id":"524191","messageId":"xmqqbjohy2op.fsf@gitster.g","threadId":"63947","inReplyTo":"63c9e0361dc02c15afeea3cad1656e1631637f60.1755127218.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 2/4] doc: git-add: simplify discussion of ignored files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-14T22:10:46Z","receivedAt":"2025-08-14T22:10:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" writes:\n\n> -The `git add` command will not add ignored files by default. If any\n> -ignored files were explicitly specified on the command line, `git add`\n> -will fail with a list of ignored files. Ignored files reached by\n> -directory recursion or filename globbing performed by Git (quote your\n> -globs before the shell) will be silently ignored. The `git add` command can\n> -be used to add ignored files with the `-f` (force) option.\n\n\n> +`git add` will not add ignored files by default. You can use the\n> +`--force` option to add ignored files. If you explicitly specify the\n> +exact filename of an ignored file (e.g. `git add ignored.txt`), `git\n> +add` will fail with a list of ignored files. Otherwise it will silently\n> +ignore the file.\n\nI think we no longer need to say \"explicitly\" now that we added\n\"exact\".\n\nThe earlier text used \"explicitly\" because it wanted to say that\n\"git add t/ 'ig*.txt'\" silently ignores \"t/ignored-file.txt\" and\n\"ignored-file.txt\" because these files are not explicitly named\n(they were only implicitly named via recursion or globbing). Your\nnew wording \"exact filename\" already covers these cases.\n\nDo we discuss that \"git add t/\" attempts to add everything that is\nnot ignored under the t/ directory elsewhere in this document after\nthese patches? If we do, then I am 100% OK with the decision to\nstop talking about globs and recursion in this paragraph. Otherwise,\nI would want to see some mention of this \"naming directory names its\ncontents recursively\" somewhere in the document (it does not have to\nbe, but can naturally be, in this paragraph).\n\nThanks.\n\n\n"},{"id":"524194","messageId":"xmqq349ty254.fsf@gitster.g","threadId":"63947","inReplyTo":"ce1eafb02860b390da9359f92fcf098b7cdd3a94.1755127218.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 3/4] doc: git-add: make explanation less dry","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-14T22:22:31Z","receivedAt":"2025-08-14T22:22:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" writes:\n\n> -This command can be performed multiple times before a commit. It only\n> -adds the content of the specified file(s) at the time the add command is\n> -run; if you want subsequent changes included in the next commit, then\n> -you must run `git add` again to add the new content to the index.\n> +The `git add` command only adds the changes at the time that you run it.\n> +If you edit `file.c` after adding it, you need to run `git add file.c`\n> +again before committing.\n\nI somehow find the text before this change easier to understand\n(except for one thing). \"If you edit `file.c` after adding it\" in\nthe new text says the same thing as \"if you want subsequent ... in\nthe next commit\" in the original but in a much better way.\n\n> -The `git status` command can be used to obtain a summary of which\n> -files have changes that are staged for the next commit.\n> +If you want to check which changes have been added, you can run\n> +`git status` to print out a summary of the changes that will be committed\n> +or run `git diff --staged` to see the full diff.\n\nRewrite \"diff --staged\" to \"diff --cached\", simply because that is\nhow \"git diff -h\" shows. After all, \"--staged\" is explained as a\n\"synonym\" (and by definition, a synonym is something that you do not\nhave to use, as you can use the real thing).\n\n\"status\" gives paths in two groups, \"changes to be committed\" and\n\"changes not staged for commit\". Explaining the use of \"diff\n--cached\" to inspect what the user will be committing is a great\naddition here, as it is a sensible way to sanity-check the result of\nyour index manipulations. In addition, we also should talk about\n\"diff\" to inspect what the user will be leaving out---in other\nwords, what the user might have forgotten to add, which is equally\nif not more useful sanity-check you can do before you commit.\n\nThanks.\n"},{"id":"524195","messageId":"xmqqldnlwmc5.fsf@gitster.g","threadId":"63947","inReplyTo":"9e595f9ad59776d74a431731824410c7b73795dd.1755127218.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 4/4] doc: git-add: explain inconsistent terminology","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-14T22:49:14Z","receivedAt":"2025-08-14T22:49:17Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" writes:\n\n> From: Julia Evans \n>\n> I think the fact that git uses these three terms interchangeably is\n> extremely confusing and that it deserves to be noted.\n\nWe tend to avoid saying \"I think\" in our proposed log messages, as\nwe do not churn the code and documentation merely to match personal\npreferences.\n\nI do not necessarily think \"git add --help\" is an appropriate place\nto leave this note, by the way. We should start from teaching \"git\nhelp glossary\", which does not mention \"staging area\" at all, which\nis a sign that it is somewhat outdated. It does not use the verb\n'to stage' even once, either.\n\nHere is my attempt to improve the situation by giving a definition\nof \"staging area\" in the glossary. Luckily, \"cache\" already has its\nown entry, describing it as an old synonym to the 'index', so I\ndidn't have to do anything there. Also the description of 'index'\nhas a bit too much implementation detail, which I toned down.\n\n---\nSubject: glossary: talk about \"staging area\"\n\nSurprisingly, \"git help glossary\" does not mention the 'staging\narea' synonym for the index, or the verb 'to stage'. As \"git\nstatus\" output uses the latter (i.e. \"Changes not staged for\ncommit\"), we should not leave it undefined what the verb means.\n\nRewrite the definition of the `index` somewhat to reduce the level\nof implementation detail exposed, and focus more on the fact that it\nis a mapping from pathnames to the contents at these paths. And\nmention the `staging area` there, as well as giving its own glossary\nentry.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/glossary-content.adoc | 20 +++++++++++++++-----\n 1 file changed, 15 insertions(+), 5 deletions(-)\n\ndiff --git c/Documentation/glossary-content.adoc w/Documentation/glossary-content.adoc\nindex e423e4765b..10f0c21e88 100644\n--- c/Documentation/glossary-content.adoc\n+++ w/Documentation/glossary-content.adoc\n@@ -247,11 +247,15 @@ for a more flexible and robust system to do the same thing.\n \tof Git you had to make them executable.\n \n [[def_index]]index::\n-\tA collection of files with stat information, whose contents are stored\n-\tas objects. The index is a stored version of your\n-\t<>. Truth be told, it can also contain a second, and even\n-\ta third version of a working tree, which are used\n-\twhen <>.\n+\tThe index stores the mapping from filenames to their contents\n+\tto prepare the contents of the next commit by updating the\n+\tobject recorded for each path (for this reason, people often\n+\tsay that the index is \"like the staging area\" when explaining\n+\tthe concept), together with other information to detect which\n+\tworking tree files are modified efficiently.\n+\tDuring a conflicted <>, the index can have\n+\tmultiple versions of contents at higher stages for the same\n+\tpath.\n \n [[def_index_entry]]index entry::\n \tThe information regarding a particular file, stored in the\n@@ -650,6 +654,12 @@ the `refs/tags/` hierarchy is used to represent local tags..\n \tis created by giving the `--depth` option to linkgit:git-clone[1], and\n \tits history can be later deepened with linkgit:git-fetch[1].\n \n+[[def_stage]]staging area::\n+\tA synonym for <>. Adding contents to the\n+\tindex to update the mapping from the filename to its contents\n+\tis often called \"to stage\" (verb), as people explain the index\n+\tis like a staging area to prepare for the next commit.\n+\n [[def_stash]]stash entry::\n \tAn <> used to temporarily store the contents of a\n \t<> working directory and the index for future reuse.\n"},{"id":"524201","messageId":"xmqqikipv2p6.fsf@gitster.g","threadId":"63947","inReplyTo":"d041d09589b51734a8cc257f80cdaf210c6676e7.1755127218.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 1/4] doc: git-add: start man page with an example","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-15T00:38:45Z","receivedAt":"2025-08-15T00:38:47Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" writes:\n\n> -git-add - Add file contents to the index\n> +git-add - Add new or changed files to the index\n\nDoes it add much value to say \"new or changed\" here? The command can\nalso be used to \"stage\" a removal of a path, e.g.\n\n $ rm tracked-file\n $ git add -u\n\nso if the updated text is an attempt to give more details on what\nkind of modifications are captured, it would be better to say \"add\nnew, removed, or modified files\".\n\n> +Add new or changed files to the index to prepare for a commit. The\n> +\"index\" (also known as \"staging area\") is where Git stores the changes\n> +that will be in the next commit.\n\nI won't repeat myself about change-snapshot duality, but I do not\nthink the new text is the best we can do.\n\n Update contents recorded in the index to prepare for the next\n commit. The index (also known as \"staging area\") is where Git\n stores the contents that will be in the next commit.\n\n> +By default, `git commit` only commits changes that you've added to the\n> +index.\n> For example, if you've edited `file.c` and want to commit your\n> +changes, you can run:\n\nLikewise. \"and want to record the resulting contents\".\n\n> ...\n> -Please see linkgit:git-commit[1] for alternative ways to add content to a\n> -commit.\n\nIn the original, this comment does look a bit out of place (as the\ntext around there does not talk about `git commit`), but as you said\nthat by default 'git commit' makes an as-is commit above, it may be\na good idea to move this sentence there. `git commit ` is\na handy thing to know even for beginners, and making your next commit\nis what the user is working towards by using \"git add\".\n"},{"id":"524228","messageId":"xmqqy0rlta8q.fsf@gitster.g","threadId":"63947","inReplyTo":"e1c9f388-f72c-4bb4-b05d-b5b183501456@app.fastmail.com","subject":"Re: [PATCH 2/5] doc: git-add: start man page with an example","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-15T05:38:45Z","receivedAt":"2025-08-15T05:38:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" writes:\n\n> This example makes me think that if we want people to understand the\n> limitations of the index, it's important to communicate that the past\n> index snapshots are *discarded* and not just that the index is a snapshot.\n\nI suspect that you need to look at the whole thing backwards. I\nrealize that it is another way to say that you are looking at the\nwhole thing backwards, so take your pick ;-).\n\nNobody stops you from extending the system to store more than one\nsnapshots in the index and allow your users to roll back to one of\nthese snapshots kept in the index. The reason why we haven't done\nso is because there has not been motivating any use case for such a\nfeature (and coming up with a reasonable UI for it would also be\nmore work). After all, if you want to keep a set of good points to\ngo back to [*], that is what commits are for in the world view of\nGit, where creating commits and moving around in history are cheap.\nIf it were something worth going back to, you'd do so at the commit\nlevel. \"git stash\" and its index operations (like the \"--keep\"\noption that allows you to test with only what is in the index) are\nimplemented as (temporary) commits internally exactly for this\nreason.\n\nHaving said that, there is a focused support to record the previous\nstate before a snapshot records a resolution for a conflicted path\n[**]. This was added because of a concrete motivating use case to\nallow you to recover from a botched conflict resolution (aka \"gee, I\nthought this resolution was OK but I did 'git add' way too early,\nbefore I actually tested the result!\"), where \"you can commit to\nmark the place to later go back\" principle does not cleanly apply,\nsince commits in Git do not record conflicted state.\n\nPlease don't keep asking \"why\" on this point (i.e. \"why not record\nconflicts in commit?\") and other things---at some point, the answers\nwill become a series of \"that is how it is, and it has been good\nenough for us\", and then it becomes a waste of time to further ask\n\"why\". Until \"here is the change I made to do things differently;\nplease see how well it works\" materializes, that is.\n\n\n[Footnote]\n\n * This is another example why the snapshot worldview gives clear\n workflow. After you pile on several drunken-walk experimental\n commits on top of a good commit and realize that this particular\n line of effort is leading nowhere, you \"jump back\" to that known\n good point (i.e. \"git reset --hard HEAD~7\"). You do not have to\n apply these changes in reverse direction (i.e. \"git apply -R\") in\n reverse order (i.e. \"git rev-list --reverse HEAD~7..\".\n\n** Read about \"Resolve undo\" in the documentation.\n"},{"id":"524241","messageId":"5004213.GXAFRqVoOG@cayenne","threadId":"63947","inReplyTo":"xmqqikipv2p6.fsf@gitster.g","subject":"Re: [PATCH v2 1/4] doc: git-add: start man page with an example","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2025-08-15T13:34:41Z","receivedAt":"2025-08-15T13:34:54Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On Friday, 15 August 2025 02:38:45 CEST Junio C Hamano wrote:\n> \"Julia Evans via GitGitGadget\" writes:\n> > -git-add - Add file contents to the index\n> > +git-add - Add new or changed files to the index\n> \n> Does it add much value to say \"new or changed\" here? The command can\n> also be used to \"stage\" a removal of a path, e.g.\n> \n> $ rm tracked-file\n> $ git add -u\n> \n> so if the updated text is an attempt to give more details on what\n> kind of modifications are captured, it would be better to say \"add\n> new, removed, or modified files\".\n> \n\nThe way I see it is that git add *captures* a part of the current state of the \nworking tree (be it addition/removal of contents of files or subtrees of the \nworking dir) for the next commit. A commit *is* a snapshot of the state of the \nproject. The concept of snapshot is central to understanding the behavior of \ngit and its internals.\n\n> > +Add new or changed files to the index to prepare for a commit. The\n> > +\"index\" (also known as \"staging area\") is where Git stores the changes\n> > +that will be in the next commit.\n> \n> I won't repeat myself about change-snapshot duality, but I do not\n> think the new text is the best we can do.\n> \n> Update contents recorded in the index to prepare for the next\n> commit. The index (also known as \"staging area\") is where Git\n> stores the contents that will be in the next commit.\n\nParticularly, the \"stores the changes that...\" part is really not what the \nreader should remember.\n\n> \n> > +By default, `git commit` only commits changes that you've added to the\n> > +index.\n\nI do not understand this addition. I may not be missing knowledge, but this \nbehavior is not only \"by default\", it's the only behavior of git: commits are \nmade with the content of the index. Let's not make it more complicated than it \nis already.\n\n> > For example, if you've edited `file.c` and want to commit your\n> \n> > +changes, you can run:\n> Likewise. \"and want to record the resulting contents\".\n> \n> > ...\n> > -Please see linkgit:git-commit[1] for alternative ways to add content to a\n> > -commit.\n> \n> In the original, this comment does look a bit out of place (as the\n> text around there does not talk about `git commit`), but as you said\n> that by default 'git commit' makes an as-is commit above, it may be\n> a good idea to move this sentence there. `git commit ` is\n> a handy thing to know even for beginners, and making your next commit\n> is what the user is working towards by using \"git add\".\n\n\n\n\n"},{"id":"524259","messageId":"886787d2-26b5-4451-a105-9ab522e38ad6@app.fastmail.com","threadId":"63947","inReplyTo":"xmqq349ty254.fsf@gitster.g","subject":"Re: [PATCH v2 3/4] doc: git-add: make explanation less dry","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-08-15T16:10:23Z","receivedAt":"2025-08-15T16:10:44Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"Hi,\n\n> I somehow find the text before this change easier to understand\n> (except for one thing). \"If you edit `file.c` after adding it\" in\n> the new text says the same thing as \"if you want subsequent ... in\n> the next commit\" in the original but in a much better way.\n\nI really appreciate all of this feedback. It makes me wonder if there would\nbe a better way to approach this man page. Usually when I'm revising a technical\nexplanation, I find people who are currently users of the software but who have\ntrouble understanding how it works. Then I ask them to give feedback on what's\nconfusing to them about the explanation or what questions they have.\n\nI do this because I find that often people who are extremely comfortable\nwith using the software (including me, which is why I usually spend so much\ntime collecting feedback like this!) can lose sight of what's confusing to an\n\"average user\". And every time I'm part of a discussion about documentation for\nan open source project it seems a bit strange to me for a group of people who\nall already understand the concept to be discussing what would be clearest to an\n\"average user\": surely the users themselves should be the judge of what's clear\nto them!\n\nI'm still pretty new to writing open source documentation so I don't know if\ncollecting user feedback like this is a normal part of the process, but I always\nlearn a lot from this type of feedback and it's pretty easy for me to collect\nit.\n\n> Rewrite \"diff --staged\" to \"diff --cached\"\n\nWill use `diff --cached`.\n\n> In addition, we also should talk about\n> \"diff\" to inspect what the user will be leaving out---in other\n> words, what the user might have forgotten to add, which is equally\n> if not more useful sanity-check you can do before you commit.\n\nThat makes sense to me.\n\nbest,\nJulia\n"},{"id":"524262","messageId":"xmqqqzxcr1ck.fsf@gitster.g","threadId":"63947","inReplyTo":"5004213.GXAFRqVoOG@cayenne","subject":"Re: [PATCH v2 1/4] doc: git-add: start man page with an example","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-15T16:33:47Z","receivedAt":"2025-08-15T16:33:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jean-Noël AVILA writes:\n\n> On Friday, 15 August 2025 02:38:45 CEST Junio C Hamano wrote:\n>> \"Julia Evans via GitGitGadget\" writes:\n>> ...\n>> > +By default, `git commit` only commits changes that you've added to the\n>> > +index.\n>\n> I do not understand this addition. I may not be missing knowledge, but this \n> behavior is not only \"by default\", it's the only behavior of git: commits are \n> made with the content of the index. Let's not make it more complicated than it \n> is already.\n\nI'll only react to \"the only behaviour\" part, without \"more\ncomplicated\" part.\n\nI think Julia is referring to the fact that you can record the state\nthat is different from what is in the index (or, what has been\naccumulated in the index by the past use of \"git add\" command that\nis being discussed here) with \"git commit [-i] \". You can\ndo\n\n $ edit fileA fileB ;# assume both are tracked\n $ git add fileA\n $ git commit fileB\n\nand the resulting commit will record the contents for fileA found in\nits parent (i.e. the result of \"git add fileA\" is not reflected).\nIf the last step were\n\n $ git commit -i fileB\n\nthen the resulting commit will record the contents for both fileA\nyou added with the last \"git add\" on it, and contents for fileB\nfound in the working tree at the time of \"git commit -i\" was run\n(i.e. \"git add fileB\" was not required)..\n\nBy default, after the edit of fileA&B and the add of fileA, \"git\ncommit\" would not be aware of what is currently in fileB in the\nworking tree, and records the same contents as its parent for all\npaths except for fileA, which would record what was last added with\n\"git add\" to the index.\n\n>> > For example, if you've edited `file.c` and want to commit your\n>> \n>> > +changes, you can run:\n>> Likewise. \"and want to record the resulting contents\".\n>> \n>> > ...\n>> > -Please see linkgit:git-commit[1] for alternative ways to add content to a\n>> > -commit.\n>> \n>> In the original, this comment does look a bit out of place (as the\n>> text around there does not talk about `git commit`), but as you said\n>> that by default 'git commit' makes an as-is commit above, it may be\n>> a good idea to move this sentence there. `git commit ` is\n>> a handy thing to know even for beginners, and making your next commit\n>> is what the user is working towards by using \"git add\".\n\nAnd this relates to \"more complicated\" part of your comment.\n\nI think keeping \"by default\" above and also keeping this comment\nthat hints about non-as-is commits made with \"git commit \"\nis slightly more preferrable than dropping both of them altogether.\nWith only four additional lines, we cover basic \"edit && add && commit\"\ncycle fairly completely.\n\nI am also fine to drop the mention of 'git commit' altogether, but\nit feels somewhat incomplete to not talk about commit when teaching\nadd. After all, add is one of the primary ways to prepare for the\nnext commit---putting it the other way around, you want to learn add\nprimarily because you eventually would want to make a commit.\n\nIn any case, only having one (i.e. \"by default\") and dropping the\nother (\"see linkgit:git-commit\"), like the patch did, did not make\nmuch sense to me.\n\nThanks.\n"},{"id":"524271","messageId":"CALnO6CCvL_wc9tkjHCa-9wp7fJMVDt-WHvHZnuOai5HzZb_j8w@mail.gmail.com","threadId":"63947","inReplyTo":"886787d2-26b5-4451-a105-9ab522e38ad6@app.fastmail.com","subject":"Re: [PATCH v2 3/4] doc: git-add: make explanation less dry","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-08-15T18:25:50Z","receivedAt":"2025-08-15T18:26:03Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Fri, Aug 15, 2025 at 12:10 PM Julia Evans wrote:\n>\n> Hi,\n>\n> > I somehow find the text before this change easier to understand\n> > (except for one thing). \"If you edit `file.c` after adding it\" in\n> > the new text says the same thing as \"if you want subsequent ... in\n> > the next commit\" in the original but in a much better way.\n>\n> I really appreciate all of this feedback. It makes me wonder if there would\n> be a better way to approach this man page. Usually when I'm revising a technical\n> explanation, I find people who are currently users of the software but who have\n> trouble understanding how it works. Then I ask them to give feedback on what's\n> confusing to them about the explanation or what questions they have.\n>\n> I do this because I find that often people who are extremely comfortable\n> with using the software (including me, which is why I usually spend so much\n> time collecting feedback like this!) can lose sight of what's confusing to an\n> \"average user\".\n\nThe curse of knowledge ;)\n\n> And every time I'm part of a discussion about documentation for\n> an open source project it seems a bit strange to me for a group of people who\n> all already understand the concept to be discussing what would be clearest to an\n> \"average user\": surely the users themselves should be the judge of what's clear\n> to them!\n>\n> I'm still pretty new to writing open source documentation so I don't know if\n> collecting user feedback like this is a normal part of the process, but I always\n> learn a lot from this type of feedback and it's pretty easy for me to collect\n> it.\n\nWhether it is or isn't normal, we could probably still benefit from\nthat perspective.\n\nAs Junio likes to say, a mistake being old is no good reason to carry\nit forward into the future (or replicate it). I'll take that to mean\nwe also have an opportunity to improve the inputs to documentation (as\n\"leaving out such a perspective\" would be the \"mistake\"—note I'm not\nascribing intent, malicious or otherwise!).\n\n-- \nD. Ben Knoble\n"},{"id":"524276","messageId":"xmqqsehspdtr.fsf@gitster.g","threadId":"63947","inReplyTo":"886787d2-26b5-4451-a105-9ab522e38ad6@app.fastmail.com","subject":"Re: [PATCH v2 3/4] doc: git-add: make explanation less dry","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-15T19:47:12Z","receivedAt":"2025-08-15T19:47:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" writes:\n\n> ... Then I ask them to give feedback on what's\n> confusing to them about the explanation or what questions they have.\n>\n> I do this because I find that often people who are extremely comfortable\n> with using the software (including me, which is why I usually spend so much\n> time collecting feedback like this!) can lose sight of what's confusing to an\n> \"average user\".\n\nYes, you can lose your novice status and it is hard to take it back\n;-) I agree with you that the next best thing you can do is to see\nhow well folks who still have that status do.\n\n> And every time I'm part of a discussion about documentation for\n> an open source project it seems a bit strange to me for a group of people who\n> all already understand the concept to be discussing what would be clearest to an\n> \"average user\": surely the users themselves should be the judge of what's clear\n> to them!\n\nYes, with one caveat, which is that you need to be careful to avoid\nthrowing them into local optima. A simplified world view may make\nit look easier to swallow, but depending on the kind of white lies\nyou throw at them, some of them they may have to unlearn to further\nunderstand the system.\n"},{"id":"524277","messageId":"xmqqbjogpd5a.fsf@gitster.g","threadId":"63947","inReplyTo":"CALnO6CCvL_wc9tkjHCa-9wp7fJMVDt-WHvHZnuOai5HzZb_j8w@mail.gmail.com","subject":"Re: [PATCH v2 3/4] doc: git-add: make explanation less dry","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-15T20:01:53Z","receivedAt":"2025-08-15T20:01:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"D. Ben Knoble\" writes:\n\n> As Junio likes to say, a mistake being old is no good reason to carry\n> it forward into the future (or replicate it).\n\nI say no such thing, though. What I say about past mistakes is that\nyou shouldn't use it as an excuse to make similar ones in the\nfuture.\n\nI'd prefer to let a sleeping dog lie.\n\nBut in the context of this discussion, I think what we carefully and\nhonestly need to look at are not past mistakes. It is importance to\nadjust to the new world we live in.\n\nIn early days of Git, people from older SCM systems did not grok the\nindex very well, so our explanation of the concept of index and\nadding content to it may have focused on teaching the difference\nbetween our system and the back-then-major SCM systems. Unless you\nhave used Bitkeeper, the \"you can commit and your doing so would not\nbother anybody else\" plus \"you can rewrite your private history\nuntil you can pretend to be a super developer who came to the best\nsolution with a single attempt\" freedom were something quite new,\nand we needed to educate folks the way to think and work well in the\ndistributed world. Earlier in one of my messages, I said \"making a\ncommit and switching to another commit is cheap\", and that comment\ncame out of habit, but that is only understood by folks who have\nused older SCM systems we displaced.\n\nBut with so many new users who haven't even touched anything other\nthan Git, none of the above examples certainly may not be the best\nway to teach these things to these new crop of users.\n\n"},{"id":"524292","messageId":"CALnO6CBNius_WJS=wrTHDHaQEeAd=tRHqFC6_MSJye7sOgr93A@mail.gmail.com","threadId":"63947","inReplyTo":"xmqqbjogpd5a.fsf@gitster.g","subject":"Re: [PATCH v2 3/4] doc: git-add: make explanation less dry","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-08-16T14:15:04Z","receivedAt":"2025-08-16T14:15:19Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Fri, Aug 15, 2025 at 4:01 PM Junio C Hamano wrote:\n>\n> \"D. Ben Knoble\" writes:\n>\n> > As Junio likes to say, a mistake being old is no good reason to carry\n> > it forward into the future (or replicate it).\n>\n> I say no such thing, though. What I say about past mistakes is that\n> you shouldn't use it as an excuse to make similar ones in the\n> future.\n\nFair; my apologies for misrepresenting your position :)\n\n\n> I'd prefer to let a sleeping dog lie.\n>\n> But in the context of this discussion, I think what we carefully and\n> honestly need to look at are not past mistakes. It is importance to\n> adjust to the new world we live in.\n\nAgreed, and I could have made this clearer.\n\n\n-- \nD. Ben Knoble\n"},{"id":"524325","messageId":"3896226.kQq0lBPeGt@cayenne","threadId":"63947","inReplyTo":"xmqqqzxcr1ck.fsf@gitster.g","subject":"Re: [PATCH v2 1/4] doc: git-add: start man page with an example","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2025-08-17T18:37:32Z","receivedAt":"2025-08-17T18:37:44Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On Friday, 15 August 2025 18:33:47 CEST Junio C Hamano wrote:\n> Jean-Noël AVILA writes:\n> > On Friday, 15 August 2025 02:38:45 CEST Junio C Hamano wrote:\n> >> \"Julia Evans via GitGitGadget\" writes:\n> >> ...\n> >> \n> >> > +By default, `git commit` only commits changes that you've added to the\n> >> > +index.\n> > \n> > I do not understand this addition. I may not be missing knowledge, but \nthis\n> > behavior is not only \"by default\", it's the only behavior of git: commits \nare\n> > made with the content of the index. Let's not make it more complicated \nthan it\n> > is already.\n> \n> I'll only react to \"the only behaviour\" part, without \"more\n> complicated\" part.\n> \n> I think Julia is referring to the fact that you can record the state\n> that is different from what is in the index (or, what has been\n> accumulated in the index by the past use of \"git add\" command that\n> is being discussed here) with \"git commit [-i] \". You can\n> do\n> \n> $ edit fileA fileB ;# assume both are tracked\n> $ git add fileA\n> $ git commit fileB\n> \n> and the resulting commit will record the contents for fileA found in\n> its parent (i.e. the result of \"git add fileA\" is not reflected).\n> If the last step were\n> \n> $ git commit -i fileB\n> \n> then the resulting commit will record the contents for both fileA\n> you added with the last \"git add\" on it, and contents for fileB\n> found in the working tree at the time of \"git commit -i\" was run\n> (i.e. \"git add fileB\" was not required)..\n> \n> By default, after the edit of fileA&B and the add of fileA, \"git\n> commit\" would not be aware of what is currently in fileB in the\n> working tree, and records the same contents as its parent for all\n> paths except for fileA, which would record what was last added with\n> \"git add\" to the index.\n> \n\nThanks for the explanation, I had forgotten this form of git commit. For the \nrecord, when I teach about add/commit, I never talk about the direct commit \nform, to present things in the most repeatable/unambiguous form.\n\nThe `git commit ` form may be of use for old-timers who were doing \nso with previous SCMs. But as stated elsewhere, young newcomers do not have to \nfight against finger memory. The explanation that you provided describes a \nquite complicated process with options, so this feature seems to be reserved \nto advanced users.\n \nThe manual pages in section 1 are mostly reference stuff for a given command, \nand this way of referring here to alternate usage of git commit is a bit off-\ntopic to me. For how to organize workflows, there are some pages in section 7.\n\nMy stance is as follow: yes, being complete is important in a reference piece \nof documentation, but throwing a \"by default\" on `git commit` here, without \nfurther explanation, sends the reader in an unsure state, which is detrimental \nto understanding at this early stage of the documentation.\n\nOtherwise, the idea of the simple example as an introduction is a good \naddition before delving into more formal and comprehensive explanation. The \nonly caveat is to not introduce wrong concepts that may need to be reverted \nlater.\n \n\n> >> > For example, if you've edited `file.c` and want to commit your\n> >> \n> >> > +changes, you can run:\n> >> Likewise. \"and want to record the resulting contents\".\n> >> \n> >> > ...\n> >> > -Please see linkgit:git-commit[1] for alternative ways to add content \nto a\n> >> > -commit.\n> >> \n> >> In the original, this comment does look a bit out of place (as the\n> >> text around there does not talk about `git commit`), but as you said\n> >> that by default 'git commit' makes an as-is commit above, it may be\n> >> a good idea to move this sentence there. `git commit ` is\n> >> a handy thing to know even for beginners, and making your next commit\n> >> is what the user is working towards by using \"git add\".\n> \n> And this relates to \"more complicated\" part of your comment.\n> \n> I think keeping \"by default\" above and also keeping this comment\n> that hints about non-as-is commits made with \"git commit \"\n> is slightly more preferrable than dropping both of them altogether.\n> With only four additional lines, we cover basic \"edit && add && commit\"\n> cycle fairly completely.\n> \n> I am also fine to drop the mention of 'git commit' altogether, but\n> it feels somewhat incomplete to not talk about commit when teaching\n> add. After all, add is one of the primary ways to prepare for the\n> next commit---putting it the other way around, you want to learn add\n> primarily because you eventually would want to make a commit.\n> \n> In any case, only having one (i.e. \"by default\") and dropping the\n> other (\"see linkgit:git-commit\"), like the patch did, did not make\n> much sense to me.\n> \n> Thanks.\n\nI'm not for dropping them, but for deferring the mention of this special \nworkflow later in the explanation, with the reference to `git commit`.\n\nBR\n\nJean-Noël\n\n\n\n"},{"id":"524444","messageId":"007dd7bb-352e-4682-8ca2-8256d9a47e07@app.fastmail.com","threadId":"63947","inReplyTo":"xmqqsehspdtr.fsf@gitster.g","subject":"Re: [PATCH v2 3/4] doc: git-add: make explanation less dry","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-08-19T12:57:07Z","receivedAt":"2025-08-19T12:57:28Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"> Yes, you can lose your novice status and it is hard to take it back\n> ;-) I agree with you that the next best thing you can do is to see\n> how well folks who still have that status do.\n\nI've returned with some data! I got feedback on the `git-add` man page from\n13 Git users. It's a group of pretty experienced users: half of them have been\nusing Git for 5-10 years, and about half for 10+ years. Even though there are\nno \"novices\" here, they still provided useful feedback about what's confusing.\n\nHere's what I took away from the feedback and a summary of the comments. \nFirst, what I took away:\n\n* The term \"index\" is hard to understand even for very experienced Git users,\n and even for some users who say that they are extremely comfortable with Git.\n* The second sentence in the man page is too long and hard to parse.\n* The \"(quote your globs before the shell)\" phrasing is confusing.\n* I thought mentioning that you can use `git reset` to undo a `git add` was a\n good idea.\n* Leaving something similar to the existing phrasing around \"snapshot\" seems\n fine, nobody in this group was confused, though of course this is a group\n of people who already understand how `git add` works.\n\nHere's my summary of the comments on the existing man page. I collected them\nusing this little tool I built: https://text-feedback.wizardzines.com/git-add/.\nI'm happy to also figure out how to best share the \"raw\" comments if folks would\nfind that helpful. I've quoted the current man page text for context.\n\n> This command updates the index using the current content found in the working\n> tree, to prepare the content staged for the next commit. It typically adds the\n> current content of existing paths as a whole, but with some options it can also\n> be used to add content with only part of the changes made to the working tree\n> files applied, or remove paths that do not exist in the working tree anymore.\n\nThis was the paragraph with the most \"this is confusing\" comments. Here are the\nmain themes:\n\n1. 7 people (more than half) said that they find the term \"index\" confusing. A\n few example quotes:\n * \"updates the index\" sounds like it increments something\"\n * \"Is the index not just the content that is staged for commit? Do I as an\n\t end user need to care about the difference? I've not heard the staged\n\t content referred to as the index before, even in git command outputs.\"\n2. 3 people said the second sentence is too long and hard to parse\n3. 2 people said that \"It *typically* adds the current content of existing\n paths\" is confusing (What's meant by \"typically\"? When does it not do that?\n is this referring to git add -A?)\n\n> The \"index\" holds a snapshot of the content of the working tree, and it is\n> this snapshot that is taken as the contents of the next commit. Thus after\n> making any changes to the working tree, and before running the commit\n> command, you must use the add command to add any new or modified\n> files to the index.\n\nNobody said they were confused by this, other than continued confusion around\nthe term \"index\", like:\n\n* \"Why quotes around \"index\" here but not when I first encounter the word\n index?\"\n* \"I'm guessing index is used through git man pages and staging area is a newer\n way of saying this 🤔\"\n* \"Can we just say staging area? I don't think of adding changes to the \"index\"\"\n\nComments not related to the term \"index\":\n\n* \"Would prefer something more direct like \"git lets you gradually build the\n contents of the next commit by adding things to the staging area...\"\"\n* \"I wish this came first in the description.\"\n* One person said they appreciated \"you must use the add command [after making\n any changes]\", since that confused them when they started using git\n\n> This command can be performed multiple times before a commit. It only adds the\n> content of the specified file(s) at the time the add command is run; if you\n> want subsequent changes included in the next commit, then you must run git add\n> again to add the new content to the index.\n\nNo comments other than \"Can be improved to be more clear.\"\n\n> Ignored files reached by directory recursion or filename globbing performed\n> by Git (quote your globs before the shell)\n\n4 people did not understand what \"(quote your globs before the shell)\" meant.\n(\"Does it mean that I need to escape glob quotation marks?\").\n\n> The git status command can be used to obtain a summary of which files have\n> changes that are staged for the next commit.\n\nNobody said they were confused by this. One person said they were happy it was\nmentioned, and one person suggested replacing \"obtain\" with \"get\".\n\nThings people said they learned from the man page:\n\n1. \"I did not know that the globs would be treated potentially differently if\n expanded by the shell before getting to git.\"\n2. \"I never knew git could do globbing.\"\n3. \"I didn't know you could remove paths with add\"\n\nThings people suggested adding:\n\n1. \"This should also document how to undo the effects of \"git add\". I'm always\n confused between how best to do so between \"git restore\" and \"git reset\".\"\n"},{"id":"524477","messageId":"44ae4747-e9f5-4d46-8793-9c57dd184f91@app.fastmail.com","threadId":"63947","inReplyTo":"3896226.kQq0lBPeGt@cayenne","subject":"Re: [PATCH v2 1/4] doc: git-add: start man page with an example","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-08-19T20:01:42Z","receivedAt":"2025-08-19T20:02:04Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":">> I think Julia is referring to the fact that you can record the state\n>> that is different from what is in the index (or, what has been\n>> accumulated in the index by the past use of \"git add\" command that\n>> is being discussed here) with \"git commit [-i] \". You can\n>> do\n>> \n>> $ edit fileA fileB ;# assume both are tracked\n>> $ git add fileA\n>> $ git commit fileB\n\nI was actually thinking of `git commit -a`, but it amounts to the same thing.\n\nI'm going to remove the \"By default\": I agree it introduces some\nunnecessary confusion, similar to the \"It typically adds...\" in the current\nversion of the man page. I'll instead be more explicit:\n\"When you run `git commit` without any other arguments..\"\n"},{"id":"524479","messageId":"f168115c-1ec4-4723-94ac-7e22dfcedb39@app.fastmail.com","threadId":"63947","inReplyTo":"xmqqldnlwmc5.fsf@gitster.g","subject":"Re: [PATCH v2 4/4] doc: git-add: explain inconsistent terminology","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-08-19T20:09:08Z","receivedAt":"2025-08-19T20:09:29Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"> Here is my attempt to improve the situation by giving a definition\n> of \"staging area\" in the glossary. Luckily, \"cache\" already has its\n> own entry, describing it as an old synonym to the 'index', so I\n> didn't have to do anything there. Also the description of 'index'\n> has a bit too much implementation detail, which I toned down.\n\nI love the idea of improving the glossary, but I'm concerned that\nglossary isn't very discoverable -- I didn't even know Git had\na glossary until relatively recently.\n\nI think we can be much more brief about resolving this confusion though --\nfrom the user feedback, all users seem to want to know is whether \"index\" and\n\"staging area\" mean the same thing, and that we can clear that up in just a few\nwords -- 'index (also known as \"staging area\")'.\n"},{"id":"524481","messageId":"pull.1952.v3.git.1755636370.gitgitgadget@gmail.com","threadId":"63947","inReplyTo":"pull.1952.v2.git.1755127218.gitgitgadget@gmail.com","subject":"[PATCH v3 0/3] doc: git-add: clarify DESCRIPTION section","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-19T20:46:07Z","receivedAt":"2025-08-19T20:46:13Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":" * Emphasize \"contents\" more than \"files\" in the introduction\n * Delete the terminology note, and just keep a single parenthetical \"(also\n known as \"staging area\")\"\n * Be more explicit about what \"By default\" means\n * Don't mention git diff --cached, mentioning more and more related\n commands felt like it was starting to get messy (what about git diff?\n what about git reset? what about git rm?).\n * Leave the \"This command can be performed multiple times before a\n commit\"... paragraph alone since the only 2 users who commented on it\n said it was clear and helpful already.\n * Move \"Please see linkgit:git-commit[1]..\" back to the end, where it used\n to be\n\nJulia Evans (2):\n doc: git-add: clarify intro & add an example\n doc: git-add: simplify discussion of ignored files\n\nJunio C Hamano (1):\n Git 2.51\n\n Documentation/git-add.adoc | 34 ++++++++++++++++------------------\n GIT-VERSION-GEN | 2 +-\n 2 files changed, 17 insertions(+), 19 deletions(-)\n\n\nbase-commit: e5ab6b3e5a3f0a94a429526e0fe6f491955ac053\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1952%2Fjvns%2Fclarify-add-v3\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1952/jvns/clarify-add-v3\nPull-Request: https://github.com/gitgitgadget/git/pull/1952\n\nRange-diff vs v2:\n\n -: ----------- > 1: c44beea485f Git 2.51\n 1: d041d09589b ! 2: 080720c0599 doc: git-add: start man page with an example\n @@ Metadata\n Author: Julia Evans \n \n ## Commit message ##\n - doc: git-add: start man page with an example\n + doc: git-add: clarify intro & add an example\n \n - - Replace the intro paragraph of the `git-add` man page with an\n - example to try to clarify it for new users. The goal here is use less\n - jargon but communicate essentially the same information.\n - - Give an example of how to add only part of the changes to the file\n - - Remove the snapshot-based explanation of the index and replace it with\n - a diff-based explanation because I don't feel that it's useful in this\n - context to emphasize that git uses a snapshot-based model: the main\n - way most git users interact with the index is through `git diff` or\n - `git status`, which is a completely diff-based view of the index.\n + - Add a basic example of how \"git add\" is normally used\n + - It's not technically true that you *must* use the `add` command to\n + add changes before running `git commit`, because `git commit -a`\n + exists. Instead say that you *can* use the `add` command.\n + - Mention early on that \"index\" is another word for \"staging area\",\n + since Git very rarely uses the word \"index\" in its output\n + (`git status`) uses the term \"staged\", and many Git users are\n + unfamiliar with the term \"index\"\n + - Remove \"It typically adds\" (it's not clear what \"typically\" means),\n + and instead mention that `git add -p` can be used to add\n + partial contents\n + - Currently the introduction is somewhat repetitive (\"to prepare the\n + content staged for the next commit\" ... \"this snapshot that is taken\n + as the contents of the next commit.\"), replace with a single sentence\n + (\"The \"index\" [...] is where Git stores the contents of the next\n + commit.\")\n \n Signed-off-by: Julia Evans \n \n ## Documentation/git-add.adoc ##\n -@@ Documentation/git-add.adoc: git-add(1)\n - \n - NAME\n - ----\n --git-add - Add file contents to the index\n -+git-add - Add new or changed files to the index\n - \n - SYNOPSIS\n - --------\n @@ Documentation/git-add.adoc: git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [-\n \n DESCRIPTION\n @@ Documentation/git-add.adoc: git add [--verbose | -v] [--dry-run | -n] [--force |\n -after making any changes to the working tree, and before running\n -the commit command, you must use the `add` command to add any new or\n -modified files to the index.\n -+Add new or changed files to the index to prepare for a commit. The\n -+\"index\" (also known as \"staging area\") is where Git stores the changes\n -+that will be in the next commit.\n ++Add contents of new or changed files to the index. The \"index\" (also\n ++known as \"staging area\") is where Git stores the contents of the next\n ++commit.\n +\n -+By default, `git commit` only commits changes that you've added to the\n -+index. For example, if you've edited `file.c` and want to commit your\n -+changes, you can run:\n ++When you run `git commit` without any other arguments, it will only\n ++commit staged changes. For example, if you've edited `file.c` and want\n ++to commit your changes to that file, you can run:\n +\n + git add file.c\n + git commit\n +\n +You can also add only part of your changes to a file with `git add -p`.\n -+Please see linkgit:git-commit[1] for alternative ways to add content to\n -+a commit.\n \n This command can be performed multiple times before a commit. It only\n adds the content of the specified file(s) at the time the add command is\n -@@ Documentation/git-add.adoc: directory recursion or filename globbing performed by Git (quote your\n - globs before the shell) will be silently ignored. The `git add` command can\n - be used to add ignored files with the `-f` (force) option.\n - \n --Please see linkgit:git-commit[1] for alternative ways to add content to a\n --commit.\n --\n --\n - OPTIONS\n - -------\n - `...`::\n 2: 63c9e0361dc ! 3: fc2ec305a9e doc: git-add: simplify discussion of ignored files\n @@ Commit message\n \n - Mention the --force option earlier\n - Remove the explanation of shell globbing vs git's internal glob\n - system, it's a common gotcha but I don't think this is an appropriate\n - place to explain that concept. There's some discussion of the gotchas\n - around globbing and `git add` in the EXAMPLES section which I think\n - is clearer.\n + system, since users are confused by it and there's a clearer\n + discussion in the EXAMPLES section.\n \n Signed-off-by: Julia Evans \n \n @@ Documentation/git-add.adoc: you must run `git add` again to add the new content\n -directory recursion or filename globbing performed by Git (quote your\n -globs before the shell) will be silently ignored. The `git add` command can\n -be used to add ignored files with the `-f` (force) option.\n -+`git add` will not add ignored files by default. You can use the\n -+`--force` option to add ignored files. If you explicitly specify the\n -+exact filename of an ignored file (e.g. `git add ignored.txt`), `git\n -+add` will fail with a list of ignored files. Otherwise it will silently\n -+ignore the file.\n ++The `git add` command will not add ignored files by default. You can\n ++use the `--force` option to add ignored files. If you specify the exact\n ++filename of an ignored file, `git add` will fail with a list of ignored\n ++files. Otherwise it will silently ignore the file.\n \n - OPTIONS\n - -------\n + Please see linkgit:git-commit[1] for alternative ways to add content to a\n + commit.\n 3: ce1eafb0286 < -: ----------- doc: git-add: make explanation less dry\n 4: 9e595f9ad59 < -: ----------- doc: git-add: explain inconsistent terminology\n\n-- \ngitgitgadget\n"},{"id":"524482","messageId":"c44beea485f0f2feaf460e2ac87fdd5608d63cf0.1755636370.git.gitgitgadget@gmail.com","threadId":"63947","inReplyTo":"pull.1952.v3.git.1755636370.gitgitgadget@gmail.com","subject":"[PATCH v3 1/3] Git 2.51","fromName":"Junio C Hamano via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-19T20:46:08Z","receivedAt":"2025-08-19T20:46:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"From: Junio C Hamano \n\nSigned-off-by: Junio C Hamano \n---\n GIT-VERSION-GEN | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/GIT-VERSION-GEN b/GIT-VERSION-GEN\nindex be801415bddc..64cbc5833536 100755\n--- a/GIT-VERSION-GEN\n+++ b/GIT-VERSION-GEN\n@@ -1,6 +1,6 @@\n #!/bin/sh\n \n-DEF_VER=v2.51.0-rc2\n+DEF_VER=v2.51.0\n \n LF='\n '\n-- \ngitgitgadget\n\n"},{"id":"524483","messageId":"fc2ec305a9eb267b7705c34c1b3bcdfa26207af8.1755636370.git.gitgitgadget@gmail.com","threadId":"63947","inReplyTo":"pull.1952.v3.git.1755636370.gitgitgadget@gmail.com","subject":"[PATCH v3 3/3] doc: git-add: simplify discussion of ignored files","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-19T20:46:10Z","receivedAt":"2025-08-19T20:46:15Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\n- Mention the --force option earlier\n- Remove the explanation of shell globbing vs git's internal glob\n system, since users are confused by it and there's a clearer\n discussion in the EXAMPLES section.\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-add.adoc | 10 ++++------\n 1 file changed, 4 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc\nindex 19f99b0e7f6f..bf793d289493 100644\n--- a/Documentation/git-add.adoc\n+++ b/Documentation/git-add.adoc\n@@ -37,12 +37,10 @@ you must run `git add` again to add the new content to the index.\n The `git status` command can be used to obtain a summary of which\n files have changes that are staged for the next commit.\n \n-The `git add` command will not add ignored files by default. If any\n-ignored files were explicitly specified on the command line, `git add`\n-will fail with a list of ignored files. Ignored files reached by\n-directory recursion or filename globbing performed by Git (quote your\n-globs before the shell) will be silently ignored. The `git add` command can\n-be used to add ignored files with the `-f` (force) option.\n+The `git add` command will not add ignored files by default. You can\n+use the `--force` option to add ignored files. If you specify the exact\n+filename of an ignored file, `git add` will fail with a list of ignored\n+files. Otherwise it will silently ignore the file.\n \n Please see linkgit:git-commit[1] for alternative ways to add content to a\n commit.\n-- \ngitgitgadget\n"},{"id":"524484","messageId":"080720c059910c910161e250cd7eef54208c3fc6.1755636370.git.gitgitgadget@gmail.com","threadId":"63947","inReplyTo":"pull.1952.v3.git.1755636370.gitgitgadget@gmail.com","subject":"[PATCH v3 2/3] doc: git-add: clarify intro & add an example","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-19T20:46:09Z","receivedAt":"2025-08-19T20:46:15Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\n- Add a basic example of how \"git add\" is normally used\n- It's not technically true that you *must* use the `add` command to\n add changes before running `git commit`, because `git commit -a`\n exists. Instead say that you *can* use the `add` command.\n- Mention early on that \"index\" is another word for \"staging area\",\n since Git very rarely uses the word \"index\" in its output\n (`git status`) uses the term \"staged\", and many Git users are\n unfamiliar with the term \"index\"\n- Remove \"It typically adds\" (it's not clear what \"typically\" means),\n and instead mention that `git add -p` can be used to add\n partial contents\n- Currently the introduction is somewhat repetitive (\"to prepare the\n content staged for the next commit\" ... \"this snapshot that is taken\n as the contents of the next commit.\"), replace with a single sentence\n (\"The \"index\" [...] is where Git stores the contents of the next\n commit.\")\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-add.adoc | 24 ++++++++++++------------\n 1 file changed, 12 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc\nindex b7a735824d6c..19f99b0e7f6f 100644\n--- a/Documentation/git-add.adoc\n+++ b/Documentation/git-add.adoc\n@@ -16,18 +16,18 @@ git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [-\n \n DESCRIPTION\n -----------\n-This command updates the index using the current content found in\n-the working tree, to prepare the content staged for the next commit.\n-It typically adds the current content of existing paths as a whole,\n-but with some options it can also be used to add content with\n-only part of the changes made to the working tree files applied, or\n-remove paths that do not exist in the working tree anymore.\n-\n-The \"index\" holds a snapshot of the content of the working tree, and it\n-is this snapshot that is taken as the contents of the next commit. Thus\n-after making any changes to the working tree, and before running\n-the commit command, you must use the `add` command to add any new or\n-modified files to the index.\n+Add contents of new or changed files to the index. The \"index\" (also\n+known as \"staging area\") is where Git stores the contents of the next\n+commit.\n+\n+When you run `git commit` without any other arguments, it will only\n+commit staged changes. For example, if you've edited `file.c` and want\n+to commit your changes to that file, you can run:\n+\n+ git add file.c\n+ git commit\n+\n+You can also add only part of your changes to a file with `git add -p`.\n \n This command can be performed multiple times before a commit. It only\n adds the content of the specified file(s) at the time the add command is\n-- \ngitgitgadget\n\n"},{"id":"524487","messageId":"011b01dc114d$201c45b0$6054d110$@nexbridge.com","threadId":"63947","inReplyTo":"c44beea485f0f2feaf460e2ac87fdd5608d63cf0.1755636370.git.gitgitgadget@gmail.com","subject":"RE: [PATCH v3 1/3] Git 2.51","fromName":"","fromEmail":"rsbecker@nexbridge.com","sentAt":"2025-08-19T21:06:20Z","receivedAt":"2025-08-19T21:06:32Z","isPatch":true,"sender":{"key":"randall.becker@nexbridge.ca","avatar":"https://avatars.githubusercontent.com/u/28956764?v=4"},"body":"On August 19, 2025 4:46 PM, Junio C Hamano wrote:\n>Signed-off-by: Junio C Hamano \n>---\n> GIT-VERSION-GEN | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n>diff --git a/GIT-VERSION-GEN b/GIT-VERSION-GEN index\n>be801415bddc..64cbc5833536 100755\n>--- a/GIT-VERSION-GEN\n>+++ b/GIT-VERSION-GEN\n>@@ -1,6 +1,6 @@\n> #!/bin/sh\n>\n>-DEF_VER=v2.51.0-rc2\n>+DEF_VER=v2.51.0\n>\n> LF='\n> '\n\nWill this cause a re-roll of the git 2.51.0 release?\n\n"},{"id":"524492","messageId":"xmqqfrdnc7s2.fsf@gitster.g","threadId":"63947","inReplyTo":"011b01dc114d$201c45b0$6054d110$@nexbridge.com","subject":"Re: [PATCH v3 1/3] Git 2.51","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-19T21:37:33Z","receivedAt":"2025-08-19T21:37:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":" writes:\n\n> On August 19, 2025 4:46 PM, Junio C Hamano wrote:\n>>Signed-off-by: Junio C Hamano \n>>---\n>> GIT-VERSION-GEN | 2 +-\n>> 1 file changed, 1 insertion(+), 1 deletion(-)\n>>\n>>diff --git a/GIT-VERSION-GEN b/GIT-VERSION-GEN index\n>>be801415bddc..64cbc5833536 100755\n>>--- a/GIT-VERSION-GEN\n>>+++ b/GIT-VERSION-GEN\n>>@@ -1,6 +1,6 @@\n>> #!/bin/sh\n>>\n>>-DEF_VER=v2.51.0-rc2\n>>+DEF_VER=v2.51.0\n>>\n>> LF='\n>> '\n>\n> Will this cause a re-roll of the git 2.51.0 release?\n\nI don't know. This is not something I did.\n"},{"id":"524493","messageId":"CALnO6CDh1PYb40UxPWj=HZgrQh6tj-PgzVqzi2eMimQrn-Ajxg@mail.gmail.com","threadId":"63947","inReplyTo":"xmqqfrdnc7s2.fsf@gitster.g","subject":"Re: [PATCH v3 1/3] Git 2.51","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-08-19T21:44:44Z","receivedAt":"2025-08-19T21:44:57Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Tue, Aug 19, 2025 at 5:37 PM Junio C Hamano wrote:\n>\n> writes:\n>\n> > On August 19, 2025 4:46 PM, Junio C Hamano wrote:\n> >>Signed-off-by: Junio C Hamano \n> >>---\n> >> GIT-VERSION-GEN | 2 +-\n> >> 1 file changed, 1 insertion(+), 1 deletion(-)\n> >>\n> >>diff --git a/GIT-VERSION-GEN b/GIT-VERSION-GEN index\n> >>be801415bddc..64cbc5833536 100755\n> >>--- a/GIT-VERSION-GEN\n> >>+++ b/GIT-VERSION-GEN\n> >>@@ -1,6 +1,6 @@\n> >> #!/bin/sh\n> >>\n> >>-DEF_VER=v2.51.0-rc2\n> >>+DEF_VER=v2.51.0\n> >>\n> >> LF='\n> >> '\n> >\n> > Will this cause a re-roll of the git 2.51.0 release?\n>\n> I don't know. This is not something I did.\n\nI also don't see any such PRs at GitGitGadget:\nhttps://github.com/gitgitgadget/git/pulls?q=2.51.0\n\nBut when triple-checking the lore archive, I realized that I think\nthis is a result of Julia's PR getting rebased on top of 2.51.0?\nhttps://github.com/gitgitgadget/git/pull/1952/commits\n\nPerhaps Julia didn't use `--keep-base`, which I often forget to do\nwhen rebasing for contribution to Git (it's common in my other\nprojects to omit it when working on the next version of a series).\nIndeed, fetching the published branch shows it's sitting on top of the\nv2.51.0 tag.\n\n-- \nD. Ben Knoble\n"},{"id":"524496","messageId":"012001dc1153$2626ff80$7274fe80$@nexbridge.com","threadId":"63947","inReplyTo":"xmqqfrdnc7s2.fsf@gitster.g","subject":"RE: [PATCH v3 1/3] Git 2.51","fromName":"","fromEmail":"rsbecker@nexbridge.com","sentAt":"2025-08-19T21:49:27Z","receivedAt":"2025-08-19T21:49:38Z","isPatch":true,"sender":{"key":"randall.becker@nexbridge.ca","avatar":"https://avatars.githubusercontent.com/u/28956764?v=4"},"body":"On August 19, 2025 5:38 PM, Junio C Hamano wrote:\n> writes:\n>\n>> On August 19, 2025 4:46 PM, Junio C Hamano wrote:\n>>>Signed-off-by: Junio C Hamano \n>>>---\n>>> GIT-VERSION-GEN | 2 +-\n>>> 1 file changed, 1 insertion(+), 1 deletion(-)\n>>>\n>>>diff --git a/GIT-VERSION-GEN b/GIT-VERSION-GEN index\n>>>be801415bddc..64cbc5833536 100755\n>>>--- a/GIT-VERSION-GEN\n>>>+++ b/GIT-VERSION-GEN\n>>>@@ -1,6 +1,6 @@\n>>> #!/bin/sh\n>>>\n>>>-DEF_VER=v2.51.0-rc2\n>>>+DEF_VER=v2.51.0\n>>>\n>>> LF='\n>>> '\n>>\n>> Will this cause a re-roll of the git 2.51.0 release?\n>\n>I don't know. This is not something I did.\n\nThanks, though, for the info.\n\n"},{"id":"524497","messageId":"44ba45b3-6020-44a0-92c5-0844b82be2f4@app.fastmail.com","threadId":"63947","inReplyTo":"CALnO6CDh1PYb40UxPWj=HZgrQh6tj-PgzVqzi2eMimQrn-Ajxg@mail.gmail.com","subject":"Re: [PATCH v3 1/3] Git 2.51","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-08-19T21:48:46Z","receivedAt":"2025-08-19T21:50:03Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"> Perhaps Julia didn't use `--keep-base`, which I often forget to do\n> when rebasing for contribution to Git (it's common in my other\n> projects to omit it when working on the next version of a series).\n> Indeed, fetching the published branch shows it's sitting on top of the\n> v2.51.0 tag.\n>\n> -- \n> D. Ben Knoble\n\nAh yeah, I didn't know I needed to do that. I can rebase on top of\nwhatever the original base was instead.\n"},{"id":"524681","messageId":"xmqqv7mgzbd5.fsf@gitster.g","threadId":"63947","inReplyTo":"080720c059910c910161e250cd7eef54208c3fc6.1755636370.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v3 2/3] doc: git-add: clarify intro & add an example","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-21T20:08:22Z","receivedAt":"2025-08-21T20:08:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" writes:\n\n> DESCRIPTION\n> -----------\n> -This command updates the index using the current content found in\n> -the working tree, to prepare the content staged for the next commit.\n> -It typically adds the current content of existing paths as a whole,\n> -but with some options it can also be used to add content with\n> -only part of the changes made to the working tree files applied, or\n> -remove paths that do not exist in the working tree anymore.\n> -\n> -The \"index\" holds a snapshot of the content of the working tree, and it\n> -is this snapshot that is taken as the contents of the next commit. Thus\n> -after making any changes to the working tree, and before running\n> -the commit command, you must use the `add` command to add any new or\n> -modified files to the index.\n> +Add contents of new or changed files to the index. The \"index\" (also\n> +known as \"staging area\") is where Git stores the contents of the next\n> +commit.\n\nMuch nicer than the preimage text that is quite awkwardly phrased.\n\nI however would not say \"Git stores the contents\", as it is you the\nuser who does the storing. I may phrase it more like \"... is what\nyou use to prepare the contents for the next commit.\" probably.\n\n> +When you run `git commit` without any other arguments, it will only\n> +commit staged changes. For example, if you've edited `file.c` and want\n> +to commit your changes to that file, you can run:\n> +\n> + git add file.c\n> + git commit\n> +\n> +You can also add only part of your changes to a file with `git add -p`.\n\nGreat.\n\n"},{"id":"524682","messageId":"xmqqqzx4zbbi.fsf@gitster.g","threadId":"63947","inReplyTo":"fc2ec305a9eb267b7705c34c1b3bcdfa26207af8.1755636370.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v3 3/3] doc: git-add: simplify discussion of ignored files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-21T20:09:21Z","receivedAt":"2025-08-21T20:09:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" writes:\n\n> -The `git add` command will not add ignored files by default. If any\n> -ignored files were explicitly specified on the command line, `git add`\n> -will fail with a list of ignored files. Ignored files reached by\n> -directory recursion or filename globbing performed by Git (quote your\n> -globs before the shell) will be silently ignored. The `git add` command can\n> -be used to add ignored files with the `-f` (force) option.\n> +The `git add` command will not add ignored files by default. You can\n> +use the `--force` option to add ignored files. If you specify the exact\n> +filename of an ignored file, `git add` will fail with a list of ignored\n> +files. Otherwise it will silently ignore the file.\n\nNice. Much simplified, yet still teaches the same thing.\n\nThanks.\n"},{"id":"524686","messageId":"2320029.iZASKD2KPV@cayenne","threadId":"63947","inReplyTo":"007dd7bb-352e-4682-8ca2-8256d9a47e07@app.fastmail.com","subject":"Re: [PATCH v2 3/4] doc: git-add: make explanation less dry","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2025-08-21T20:36:30Z","receivedAt":"2025-08-21T20:36:37Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On Tuesday, 19 August 2025 14:57:07 CEST Julia Evans wrote:\n> > Yes, you can lose your novice status and it is hard to take it back\n> > ;-) I agree with you that the next best thing you can do is to see\n> > how well folks who still have that status do.\n> \n> I've returned with some data! I got feedback on the `git-add` man page from\n> 13 Git users. It's a group of pretty experienced users: half of them have \nbeen\n> using Git for 5-10 years, and about half for 10+ years. Even though there \nare\n> no \"novices\" here, they still provided useful feedback about what's \nconfusing.\n> \n> Here's what I took away from the feedback and a summary of the comments.\n> First, what I took away:\n> \n> * The term \"index\" is hard to understand even for very experienced Git \nusers,\n> and even for some users who say that they are extremely comfortable with \nGit.\n> * The second sentence in the man page is too long and hard to parse.\n> * The \"(quote your globs before the shell)\" phrasing is confusing.\n> * I thought mentioning that you can use `git reset` to undo a `git add` was \na\n> good idea.\n> * Leaving something similar to the existing phrasing around \"snapshot\" seems\n> fine, nobody in this group was confused, though of course this is a group\n> of people who already understand how `git add` works.\n> \n> Here's my summary of the comments on the existing man page. I collected them\n> using this little tool I built: https://text-feedback.wizardzines.com/git-add/.\n> I'm happy to also figure out how to best share the \"raw\" comments if folks \nwould\n> find that helpful. I've quoted the current man page text for context.\n> \n> > This command updates the index using the current content found in the \nworking\n> > tree, to prepare the content staged for the next commit. It typically adds \nthe\n> > current content of existing paths as a whole, but with some options it can \nalso\n> > be used to add content with only part of the changes made to the working \ntree\n> > files applied, or remove paths that do not exist in the working tree \nanymore.\n> \n> This was the paragraph with the most \"this is confusing\" comments. Here are \nthe\n> main themes:\n> \n> 1. 7 people (more than half) said that they find the term \"index\" confusing. \nA\n> few example quotes:\n> * \"updates the index\" sounds like it increments something\"\n> * \"Is the index not just the content that is staged for commit? Do I as \nan\n> \t end user need to care about the difference? I've not heard the \nstaged\n> \t content referred to as the index before, even in git command \noutputs.\"\n> 2. 3 people said the second sentence is too long and hard to parse\n> 3. 2 people said that \"It *typically* adds the current content of existing\n> paths\" is confusing (What's meant by \"typically\"? When does it not do \nthat?\n> is this referring to git add -A?)\n> \n> > The \"index\" holds a snapshot of the content of the working tree, and it is\n> > this snapshot that is taken as the contents of the next commit. Thus after\n> > making any changes to the working tree, and before running the commit\n> > command, you must use the add command to add any new or modified\n> > files to the index.\n> \n> Nobody said they were confused by this, other than continued confusion \naround\n> the term \"index\", like:\n> \n> * \"Why quotes around \"index\" here but not when I first encounter the word\n> index?\"\n> * \"I'm guessing index is used through git man pages and staging area is a \nnewer\n> way of saying this 🤔\"\n> * \"Can we just say staging area? I don't think of adding changes to the \n\"index\"\"\n> \n\nFor the term index, the glossary-contents.adoc file says:\n[[def_index]]index::\n\tA collection of files with stat information, whose contents are \nstored\n\tas objects. The index is a stored version of your\n\t<>. Truth be told, it can also \ncontain a second, and even\n\ta third version of a working tree, which are used\n\twhen <>.\n\n\"Truth to be told\", this definition of the index makes things even muddier to \nme. \n\nIf I understand correctly the first ages of git, it seems that the index was a \nfile containing the list of the staged files (deletion included) with their \nstat information and hash, the actual file contents being stored in the cache. \nSo it was like an index for a book, keeping track of the name of changed files \nwith pointers to the contents of modified ones.\n\n\n\n\n"},{"id":"524734","messageId":"b30fe574-146b-4b1b-8a88-07014c9cab9d@app.fastmail.com","threadId":"63947","inReplyTo":"xmqqv7mgzbd5.fsf@gitster.g","subject":"Re: [PATCH v3 2/3] doc: git-add: clarify intro & add an example","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-08-22T20:37:21Z","receivedAt":"2025-08-22T20:37:43Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\"what you use to prepare the contents for the next commit\" sounds\ngood to me, will make those changes.\n\nOn Thu, Aug 21, 2025, at 4:08 PM, Junio C Hamano wrote:\n> \"Julia Evans via GitGitGadget\" writes:\n>\n>> DESCRIPTION\n>> -----------\n>> -This command updates the index using the current content found in\n>> -the working tree, to prepare the content staged for the next commit.\n>> -It typically adds the current content of existing paths as a whole,\n>> -but with some options it can also be used to add content with\n>> -only part of the changes made to the working tree files applied, or\n>> -remove paths that do not exist in the working tree anymore.\n>> -\n>> -The \"index\" holds a snapshot of the content of the working tree, and it\n>> -is this snapshot that is taken as the contents of the next commit. Thus\n>> -after making any changes to the working tree, and before running\n>> -the commit command, you must use the `add` command to add any new or\n>> -modified files to the index.\n>> +Add contents of new or changed files to the index. The \"index\" (also\n>> +known as \"staging area\") is where Git stores the contents of the next\n>> +commit.\n>\n> Much nicer than the preimage text that is quite awkwardly phrased.\n>\n> I however would not say \"Git stores the contents\", as it is you the\n> user who does the storing. I may phrase it more like \"... is what\n> you use to prepare the contents for the next commit.\" probably.\n>\n>> +When you run `git commit` without any other arguments, it will only\n>> +commit staged changes. For example, if you've edited `file.c` and want\n>> +to commit your changes to that file, you can run:\n>> +\n>> + git add file.c\n>> + git commit\n>> +\n>> +You can also add only part of your changes to a file with `git add -p`.\n>\n> Great.\n"},{"id":"525195","messageId":"pull.1952.v4.git.1756468502.gitgitgadget@gmail.com","threadId":"63947","inReplyTo":"pull.1952.v3.git.1755636370.gitgitgadget@gmail.com","subject":"[PATCH v4 0/2] doc: git-add: clarify DESCRIPTION section","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-29T11:55:00Z","receivedAt":"2025-08-29T11:55:05Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"Slightly reword the first sentence (\"you use\" instead of \"Git stores\")\n\nJulia Evans (2):\n doc: git-add: clarify intro & add an example\n doc: git-add: simplify discussion of ignored files\n\n Documentation/git-add.adoc | 34 ++++++++++++++++------------------\n 1 file changed, 16 insertions(+), 18 deletions(-)\n\n\nbase-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1952%2Fjvns%2Fclarify-add-v4\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1952/jvns/clarify-add-v4\nPull-Request: https://github.com/gitgitgadget/git/pull/1952\n\nRange-diff vs v3:\n\n 1: c44beea485 < -: ---------- Git 2.51\n 2: 080720c059 ! 1: 57947d5a3e doc: git-add: clarify intro & add an example\n @@ Documentation/git-add.adoc: git add [--verbose | -v] [--dry-run | -n] [--force |\n -the commit command, you must use the `add` command to add any new or\n -modified files to the index.\n +Add contents of new or changed files to the index. The \"index\" (also\n -+known as \"staging area\") is where Git stores the contents of the next\n -+commit.\n ++known as the \"staging area\") is what you use to prepare the contents of\n ++the next commit.\n +\n +When you run `git commit` without any other arguments, it will only\n +commit staged changes. For example, if you've edited `file.c` and want\n 3: fc2ec305a9 = 2: f57effdd2b doc: git-add: simplify discussion of ignored files\n\n-- \ngitgitgadget\n"},{"id":"525196","messageId":"57947d5a3effa3cafb7b4e69f5c9e999b0cc5c30.1756468502.git.gitgitgadget@gmail.com","threadId":"63947","inReplyTo":"pull.1952.v4.git.1756468502.gitgitgadget@gmail.com","subject":"[PATCH v4 1/2] doc: git-add: clarify intro & add an example","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-29T11:55:01Z","receivedAt":"2025-08-29T11:55:06Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\n- Add a basic example of how \"git add\" is normally used\n- It's not technically true that you *must* use the `add` command to\n add changes before running `git commit`, because `git commit -a`\n exists. Instead say that you *can* use the `add` command.\n- Mention early on that \"index\" is another word for \"staging area\",\n since Git very rarely uses the word \"index\" in its output\n (`git status`) uses the term \"staged\", and many Git users are\n unfamiliar with the term \"index\"\n- Remove \"It typically adds\" (it's not clear what \"typically\" means),\n and instead mention that `git add -p` can be used to add\n partial contents\n- Currently the introduction is somewhat repetitive (\"to prepare the\n content staged for the next commit\" ... \"this snapshot that is taken\n as the contents of the next commit.\"), replace with a single sentence\n (\"The \"index\" [...] is where Git stores the contents of the next\n commit.\")\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-add.adoc | 24 ++++++++++++------------\n 1 file changed, 12 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc\nindex b7a735824d..ffe8fd701a 100644\n--- a/Documentation/git-add.adoc\n+++ b/Documentation/git-add.adoc\n@@ -16,18 +16,18 @@ git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [-\n \n DESCRIPTION\n -----------\n-This command updates the index using the current content found in\n-the working tree, to prepare the content staged for the next commit.\n-It typically adds the current content of existing paths as a whole,\n-but with some options it can also be used to add content with\n-only part of the changes made to the working tree files applied, or\n-remove paths that do not exist in the working tree anymore.\n-\n-The \"index\" holds a snapshot of the content of the working tree, and it\n-is this snapshot that is taken as the contents of the next commit. Thus\n-after making any changes to the working tree, and before running\n-the commit command, you must use the `add` command to add any new or\n-modified files to the index.\n+Add contents of new or changed files to the index. The \"index\" (also\n+known as the \"staging area\") is what you use to prepare the contents of\n+the next commit.\n+\n+When you run `git commit` without any other arguments, it will only\n+commit staged changes. For example, if you've edited `file.c` and want\n+to commit your changes to that file, you can run:\n+\n+ git add file.c\n+ git commit\n+\n+You can also add only part of your changes to a file with `git add -p`.\n \n This command can be performed multiple times before a commit. It only\n adds the content of the specified file(s) at the time the add command is\n-- \ngitgitgadget\n\n"},{"id":"525197","messageId":"f57effdd2b44dd36dcae77d3c5b456b7d84c173b.1756468502.git.gitgitgadget@gmail.com","threadId":"63947","inReplyTo":"pull.1952.v4.git.1756468502.gitgitgadget@gmail.com","subject":"[PATCH v4 2/2] doc: git-add: simplify discussion of ignored files","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-29T11:55:02Z","receivedAt":"2025-08-29T11:55:07Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\n- Mention the --force option earlier\n- Remove the explanation of shell globbing vs git's internal glob\n system, since users are confused by it and there's a clearer\n discussion in the EXAMPLES section.\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-add.adoc | 10 ++++------\n 1 file changed, 4 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc\nindex ffe8fd701a..ad629c46c5 100644\n--- a/Documentation/git-add.adoc\n+++ b/Documentation/git-add.adoc\n@@ -37,12 +37,10 @@ you must run `git add` again to add the new content to the index.\n The `git status` command can be used to obtain a summary of which\n files have changes that are staged for the next commit.\n \n-The `git add` command will not add ignored files by default. If any\n-ignored files were explicitly specified on the command line, `git add`\n-will fail with a list of ignored files. Ignored files reached by\n-directory recursion or filename globbing performed by Git (quote your\n-globs before the shell) will be silently ignored. The `git add` command can\n-be used to add ignored files with the `-f` (force) option.\n+The `git add` command will not add ignored files by default. You can\n+use the `--force` option to add ignored files. If you specify the exact\n+filename of an ignored file, `git add` will fail with a list of ignored\n+files. Otherwise it will silently ignore the file.\n \n Please see linkgit:git-commit[1] for alternative ways to add content to a\n commit.\n-- \ngitgitgadget\n"},{"id":"525221","messageId":"xmqqv7m6m4sa.fsf@gitster.g","threadId":"63947","inReplyTo":"pull.1952.v4.git.1756468502.gitgitgadget@gmail.com","subject":"Re: [PATCH v4 0/2] doc: git-add: clarify DESCRIPTION section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-29T17:11:33Z","receivedAt":"2025-08-29T17:11:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" writes:\n\n> Slightly reword the first sentence (\"you use\" instead of \"Git stores\")\n\nThe update is appreciated, but the topic has already been in 'next'\nfor a few days since 2025-08-25 at 0c84501ed2, so we'd need to turn\nthis into a follow-up incremental fix.\n\nHere is what I came up with and will queue for today's integration\ncycle.\n\n--- >8 ---\nFrom: Junio C Hamano \nDate: Fri, 29 Aug 2025 10:07:42 -0700\nSubject: [PATCH] doc: rephrase the purpose of the staging area\n\nFrom: Julia Evans \n\nGit does not really \"store the contents of the next commit\"\nanywhere; rather, you the user use the index to prepare it.\n\nSigned-off-by: Julia Evans \n[jc; made the change relative to what is already in 'next']\nSigned-off-by: Junio C Hamano \n---\n Documentation/git-add.adoc | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc\nindex bf793d2894..ad629c46c5 100644\n--- a/Documentation/git-add.adoc\n+++ b/Documentation/git-add.adoc\n@@ -17,8 +17,8 @@ git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [-\n DESCRIPTION\n -----------\n Add contents of new or changed files to the index. The \"index\" (also\n-known as \"staging area\") is where Git stores the contents of the next\n-commit.\n+known as the \"staging area\") is what you use to prepare the contents of\n+the next commit.\n \n When you run `git commit` without any other arguments, it will only\n commit staged changes. For example, if you've edited `file.c` and want\n-- \n2.51.0-267-g71e270be43\n\n\n\n"}]}