On Fri, May 2, 2025 at 5:58 PM Junio C Hamano <gitster@xxxxxxxxx> wrote: > > These documents mention "whatchanged" as an example, that can be > substituted by something else. Perhaps: These documents mention "whatchanged" as an example, which can be substituted with something else. ? > A new hypothetical command "walken" > would come near "whatchanged" but since the latter may be going > away, we can say it would come near "version", as the fictitious > command sorts between them. Similarly, we do not have to use > "whatchanged" as an example of a subcommand that is also implemented > in builtin/log.c file; we can instead mention "show". > > Both of these changes allow us not to worry about adjusting these > places when "whatchanged" is finally removed. Could I suggest (now changing my previous suggestion to handle the entire commit message): doc: prepare for a world without whatchanged Some documentation examples reference `whatchanged`, either as a placeholder command or as an example of source structure. To reduce the need for future edits when `whatchanged` is removed, these references are replaced with alternatives: - In `MyFirstObjectWalk.adoc`, we use `version` as the nearby anchor point for `walken`, instead of `whatchanged`. - In `user-manual.adoc`, we now cite `show` instead of `whatchanged` as a command that coexists with `log` in builtin/log.c. This avoids needing further cleanup when `whatchanged` is retired. > Signed-off-by: Junio C Hamano <gitster@xxxxxxxxx> > --- > Documentation/MyFirstObjectWalk.adoc | 4 ++-- > Documentation/user-manual.adoc | 2 +- > 2 files changed, 3 insertions(+), 3 deletions(-) > > diff --git a/Documentation/MyFirstObjectWalk.adoc b/Documentation/MyFirstObjectWalk.adoc > index d6e9dfdbbe..102a465a48 100644 > --- a/Documentation/MyFirstObjectWalk.adoc > +++ b/Documentation/MyFirstObjectWalk.adoc > @@ -83,13 +83,13 @@ int cmd_walken(int argc, const char **argv, const char *prefix) > } > ---- > > -Also add the relevant line in `builtin.h` near `cmd_whatchanged()`: > +Also add the relevant line in `builtin.h` near `cmd_version()`: > > ---- > int cmd_walken(int argc, const char **argv, const char *prefix); > ---- > > -Include the command in `git.c` in `commands[]` near the entry for `whatchanged`, > +Include the command in `git.c` in `commands[]` near the entry for `version`, > maintaining alphabetical ordering: > > ---- > diff --git a/Documentation/user-manual.adoc b/Documentation/user-manual.adoc > index d2b478ad23..7124345966 100644 > --- a/Documentation/user-manual.adoc > +++ b/Documentation/user-manual.adoc > @@ -4240,7 +4240,7 @@ command `git`. The source side of a builtin is > - an entry in `BUILTIN_OBJECTS` in the `Makefile`. > > Sometimes, more than one builtin is contained in one source file. For > -example, `cmd_whatchanged()` and `cmd_log()` both reside in `builtin/log.c`, > +example, `cmd_show()` and `cmd_log()` both reside in `builtin/log.c`, > since they share quite a bit of code. In that case, the commands which are > _not_ named like the `.c` file in which they live have to be listed in > `BUILT_INS` in the `Makefile`. > -- > 2.49.0-601-ga5925c3955 Patch looks good.
