I agree, below reworded documentation is easier to understand. I realized I am quite poor at documenting the things (Apology for mistakes, but I learned a lot and will try my best from next time) I really appreciate all the suggestions and guidance. Thanks and Regards, Charvi On Thu, 11 Mar 2021 at 13:18, Eric Sunshine <sunshine@xxxxxxxxxxxxxx> wrote: > > On Wed, Mar 10, 2021 at 2:45 PM Charvi Mendiratta <charvi077@xxxxxxxxx> wrote: > > --- > > diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt > > @@ -86,11 +86,40 @@ OPTIONS > > +--fixup=[(amend|reword):]<commit>:: > > + Construct a new commit for use with `rebase --autosquash`, > > + which fixes the specified commit. The plain form > > + `--fixup=<commit>` creates a "fixup!" commit, that allows > > + to fixup only the content of the specified commit and leave > > + it's commit log message untouched. When used with `amend:` > > s/it's/its/ > > > + or `reword:`, it creates "amend!" commit that is like "fixup!" > > + commit but it allows to fixup both the content and the commit > > + log message of the specified commit. The commit log message of > > + the specified commit is fixed implicitly by replacing it with > > + the "amend!" commit's message body upon `rebase --autosquash`. > > The first half of this description is clear. The second half gets > bogged down and difficult to decipher. It also seems to claim that > "reword:" can change the content of <commit>, which isn't accurate at > the UI level (even if it happens to reflect the underlying > implementation). I might have written the above description like this: > > Create a new commit which "fixes up" `<commit>` when applied with > `git rebase --autosquash`. Plain `--fixup=<commit>` creates a > "fixup!" commit which changes the content of `<commit>` but leaves > its log message untouched. `--fixup=amend:<commit>` is similar but > creates an "amend!" commit which also replaces the log message of > `<commit>` with the log message of the "amend!" commit. > `--fixup=reword:<commit>` creates an "amend!" commit which > replaces the log message of `<commit>` with its own log message > but makes no changes to the content of `<commit>`. > > > +The resulting "fixup!" commit message will be the subject line > > +from the specified commit with a prefix of "fixup!". Can be used > > +with additional commit message option `-m`. > > This gives details without providing meaning. If I didn't already know > how this all works, I think I'd probably be mystified about what it is > trying to say. Providing context by mentioning `git rebase > --autosquash` would help explain the significance of "fixup!". > Similarly, it's not clear on the surface why this mentions `-m` at > all. I might have written it like this: > > The commit created by plain `--fixup=<commit>` has a subject > composed of "fixup!" followed by the subject line from <commit>, > and is recognized specially by `git rebase --autosquash`. The `-m` > option may be used to supplement the log message of the created > commit, but the additional commentary will be thrown away once the > "fixup!" commit is squashed into `<commit>` by `git rebase > --autosquash`. > > > +The `--fixup=amend:<commit>` form creates an "amend!" commit where > > +its commit message subject will be the subject line from the > > +specified commit with a prefix of "amend!" and the message body > > +will be commit log message of the specified commit. It also invokes > > +an editor seeded with the log message of the "amend!" commit to > > +allow to edit further. It refuses to create "amend!" commit if it's > > +commit message body is empty unless used with the > > +`--allow-empty-message` option. > > This is reasonable, but does get into the weeds somewhat and uses > potentially unusual terms such as "seeded". It can be tightened up a > bit by building upon what was explained earlier for plain > `--fixup=<commit>`. To really round it out and give proper context for > understanding the purpose, it would also be helpful to explain how an > "amend!" commit is handled by `git rebase --autosquash`. I might have > written it like this: > > The commit created by `--fixup=amend:<commit>` is similar but its > subject is instead prefixed with "amend!". The log message of > <commit> is copied into the log message of the "amend!" commit and > opened in an editor so it can be refined. When `git rebase > --autosquash` squashes the "amend!" commit into `<commit>`, the > log message of `<commit>` is replaced by the refined log message > from the "amend!" commit. It is an error for the "amend!" commit's > log message to be empty unless `--allow-empty-message` is > specified. > > > +The `--fixup=reword:<commit>` aliases `--fixup=amend:<commit> --only` > > +and it also creates an "amend!" commit, but here it records the same > > +tree as `HEAD`, i.e. it does not take any staged changes and only allows > > +to fixup the commit message of the specified commit. It will reword the > > +specified commit when it is rebased with `--autosquash`. > > This gets too deep into the techno-speak by talking about "tree" and > `HEAD`. You can convey the same concept more simply by saying merely > that it creates an empty commit. I might have written it like this: > > `--fixup=reword:<commit>` is shorthand for `--fixup=amend:<commit> > --only`. It creates an "amend!" commit with only a log message > (ignoring any changes staged in the index). When squashed by `git > rebase --autosquash`, it replaces the log message of `<commit>` > without making any other changes. > > > +Also, after fixing the commit using `--fixup`, with or without option > > +and rebased with `--autosquash`, the authorship of the original commit > > +remains unchanged. See linkgit:git-rebase[1] for details. > > It sounds odd to start this sentence with "also". Perhaps: > > Neither "fixup!" nor "amend!" commits change authorship of > `<commit>` when applied by `git rebase --autosquash`.
