| Message ID | 20210310194306.32565-7-charvi077@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | None | expand |
Charvi Mendiratta <charvi077@gmail.com> writes: > ---fixup=<commit>:: > - Construct a commit message for use with `rebase --autosquash`. > - The commit message will be the subject line from the specified > - commit with a prefix of "fixup! ". See linkgit:git-rebase[1] > - for details. Overall, the text in this round reads much better than the previous round. > +--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:` > + 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`. Rewriting "is fixed implicitly by replacing it with" -> "is replaced by" may make it easier to follow. Thanks.
On Thu, 11 Mar 2021 at 06:01, Junio C Hamano <gitster@pobox.com> wrote: > > +--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:` > > + 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`. > > Rewriting > > "is fixed implicitly by replacing it with" -> "is replaced by" > > may make it easier to follow. > Okay I will replace it. Thanks and Regards, Charvi
On Wed, Mar 10, 2021 at 2:45 PM Charvi Mendiratta <charvi077@gmail.com> 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`.
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@sunshineco.com> wrote: > > On Wed, Mar 10, 2021 at 2:45 PM Charvi Mendiratta <charvi077@gmail.com> 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`.
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 17150fa7ea..2de8255bdb 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git commit' [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend] - [--dry-run] [(-c | -C | --fixup | --squash) <commit>] + [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>)] [-F <file> | -m <msg>] [--reset-author] [--allow-empty] [--allow-empty-message] [--no-verify] [-e] [--author=<author>] [--date=<date>] [--cleanup=<mode>] [--[no-]status] @@ -86,11 +86,40 @@ OPTIONS Like '-C', but with `-c` the editor is invoked, so that the user can further edit the commit message. ---fixup=<commit>:: - Construct a commit message for use with `rebase --autosquash`. - The commit message will be the subject line from the specified - commit with a prefix of "fixup! ". See linkgit:git-rebase[1] - for details. +--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:` + 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 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`. ++ +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. ++ +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`. ++ +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. --squash=<commit>:: Construct a commit message for use with `rebase --autosquash`. diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 8bfa5a9272..f08ae27e2a 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -593,16 +593,17 @@ See also INCOMPATIBLE OPTIONS below. --autosquash:: --no-autosquash:: - When the commit log message begins with "squash! ..." (or - "fixup! ..."), and there is already a commit in the todo list that - matches the same `...`, automatically modify the todo list of rebase - -i so that the commit marked for squashing comes right after the - commit to be modified, and change the action of the moved commit - from `pick` to `squash` (or `fixup`). A commit matches the `...` if - the commit subject matches, or if the `...` refers to the commit's - hash. As a fall-back, partial matches of the commit subject work, - too. The recommended way to create fixup/squash commits is by using - the `--fixup`/`--squash` options of linkgit:git-commit[1]. + When the commit log message begins with "squash! ..." or "fixup! ..." + or "amend! ...", and there is already a commit in the todo list that + matches the same `...`, automatically modify the todo list of + `rebase -i`, so that the commit marked for squashing comes right after + the commit to be modified, and change the action of the moved commit + from `pick` to `squash` or `fixup` or `fixup -C` respectively. A commit + matches the `...` if the commit subject matches, or if the `...` refers + to the commit's hash. As a fall-back, partial matches of the commit + subject work, too. The recommended way to create fixup/amend/squash + commits is by using the `--fixup`, `--fixup=amend:` or `--fixup=reword:` + and `--squash` options respectively of linkgit:git-commit[1]. + If the `--autosquash` option is enabled by default using the configuration variable `rebase.autoSquash`, this option can be
Mentored-by: Christian Couder <chriscool@tuxfamily.org> Mentored-by: Phillip Wood <phillip.wood@dunelm.org.uk> Helped-by: Junio C Hamano <gitster@pobox.com> Helped-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Charvi Mendiratta <charvi077@gmail.com> --- Documentation/git-commit.txt | 41 ++++++++++++++++++++++++++++++------ Documentation/git-rebase.txt | 21 +++++++++--------- 2 files changed, 46 insertions(+), 16 deletions(-)