Re: [PATCH v2 3/4] doc: git-add: make explanation less dry

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 14, 2025, 22:22 UTC
Message-ID: <xmqq349ty254.fsf@gitster.g>
In-Reply-To: <ce1eafb02860b390da9359f92fcf098b7cdd3a94.1755127218.git.gitgitgadget@gmail.com>

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 7 quoted lines

> -This command can be performed multiple times before a commit.  It only
> -adds the content of the specified file(s) at the time the add command is
> -run; if you want subsequent changes included in the next commit, then
> -you must run `git add` again to add the new content to the index.
> +The `git add` command only adds the changes at the time that you run it.
> +If you edit `file.c` after adding it, you need to run `git add file.c`
> +again before committing.

I somehow find the text before this change easier to understand (except for one thing). "If you edit `file.c` after adding it" in the new text says the same thing as "if you want subsequent ... in the next commit" in the original but in a much better way.

Show 5 quoted lines

> -The `git status` command can be used to obtain a summary of which
> -files have changes that are staged for the next commit.
> +If you want to check which changes have been added, you can run
> +`git status` to print out a summary of the changes that will be committed
> +or run `git diff --staged` to see the full diff.

Rewrite "diff --staged" to "diff --cached", simply because that is how "git diff -h" shows. After all, "--staged" is explained as a "synonym" (and by definition, a synonym is something that you do not have to use, as you can use the real thing).

"status" gives paths in two groups, "changes to be committed" and "changes not staged for commit". Explaining the use of "diff --cached" to inspect what the user will be committing is a great addition here, as it is a sensible way to sanity-check the result of your index manipulations. In addition, we also should talk about "diff" to inspect what the user will be leaving out---in other words, what the user might have forgotten to add, which is equally if not more useful sanity-check you can do before you commit.

Thanks.