From: Charvi Mendiratta <charvi077@gmail.com>
To: Eric Sunshine <sunshine@sunshineco.com>
Cc: Git List <git@vger.kernel.org>,
Junio C Hamano <gitster@pobox.com>,
Christian Couder <chriscool@tuxfamily.org>,
Phillip Wood <phillip.wood@dunelm.org.uk>
Subject: Re: [PATCH v4 6/6] doc/git-commit: add documentation for fixup=[amend|reword] options
Date: Thu, 11 Mar 2021 20:54:25 +0530 [thread overview]
Message-ID: <CAPSFM5d7wAdh1mHZkVeRrTY3iLEqejSVDA9V-Nxb72f+eqcOcA@mail.gmail.com> (raw)
In-Reply-To: <CAPig+cQVqUGchmCxKkhw1Vffq8z68VcRujSn02KvBh78mBS2yQ@mail.gmail.com>
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`.
prev parent reply other threads:[~2021-03-11 15:25 UTC|newest]
Thread overview: 95+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-03-01 8:45 [PATCH v3 0/6][Outreachy] commit: Implementation of "amend!" commit Charvi Mendiratta
2021-03-01 8:45 ` [PATCH v3 1/6] sequencer: export subject_length() Charvi Mendiratta
2021-03-01 20:25 ` Eric Sunshine
2021-03-03 6:26 ` Junio C Hamano
2021-03-03 7:35 ` Charvi Mendiratta
2021-03-01 8:45 ` [PATCH v3 2/6] commit: add amend suboption to --fixup to create amend! commit Charvi Mendiratta
2021-03-01 18:34 ` Junio C Hamano
2021-03-03 7:32 ` Charvi Mendiratta
2021-03-01 22:15 ` Eric Sunshine
2021-03-01 22:32 ` Junio C Hamano
2021-03-01 22:47 ` Eric Sunshine
2021-03-03 7:42 ` Charvi Mendiratta
2021-03-03 7:41 ` Charvi Mendiratta
2021-03-03 7:57 ` Eric Sunshine
2021-03-03 19:21 ` Charvi Mendiratta
2021-03-04 0:58 ` Junio C Hamano
2021-03-04 9:01 ` Charvi Mendiratta
2021-03-03 7:37 ` Charvi Mendiratta
2021-03-03 7:46 ` Eric Sunshine
2021-03-03 19:21 ` Charvi Mendiratta
2021-03-01 8:45 ` [PATCH v3 3/6] commit: add a reword suboption to --fixup Charvi Mendiratta
2021-03-01 18:41 ` Junio C Hamano
2021-03-03 7:33 ` Charvi Mendiratta
2021-03-01 22:36 ` Eric Sunshine
2021-03-03 7:41 ` Charvi Mendiratta
2021-03-01 8:45 ` [PATCH v3 4/6] t7500: add tests for --fixup=[amend|reword] options Charvi Mendiratta
2021-03-02 5:43 ` Eric Sunshine
2021-03-03 6:28 ` Junio C Hamano
2021-03-03 7:43 ` Charvi Mendiratta
2021-03-01 8:45 ` [PATCH v3 5/6] t3437: use --fixup with options to create amend! commit Charvi Mendiratta
2021-03-01 8:45 ` [PATCH v3 6/6] doc/git-commit: add documentation for fixup=[amend|reword] options Charvi Mendiratta
2021-03-01 18:44 ` Junio C Hamano
2021-03-03 7:33 ` Charvi Mendiratta
2021-03-02 6:39 ` Eric Sunshine
2021-03-03 7:43 ` Charvi Mendiratta
2021-03-03 8:18 ` Eric Sunshine
2021-03-03 19:22 ` Charvi Mendiratta
2021-03-04 1:05 ` Junio C Hamano
2021-03-04 9:00 ` Charvi Mendiratta
2021-03-04 22:18 ` Junio C Hamano
2021-03-05 6:14 ` Charvi Mendiratta
2021-03-05 18:25 ` Junio C Hamano
2021-03-06 4:13 ` Charvi Mendiratta
2021-03-06 6:11 ` Eric Sunshine
2021-03-01 18:45 ` [PATCH v3 0/6][Outreachy] commit: Implementation of "amend!" commit Junio C Hamano
2021-03-03 7:33 ` Charvi Mendiratta
2021-03-10 19:43 ` [PATCH v4 " Charvi Mendiratta
2021-03-11 8:06 ` Eric Sunshine
2021-03-11 15:24 ` Charvi Mendiratta
2021-03-13 13:40 ` [PATCH v5 " Charvi Mendiratta
2021-03-13 13:40 ` [PATCH v5 1/6] sequencer: export and rename subject_length() Charvi Mendiratta
2021-03-13 13:40 ` [PATCH v5 2/6] commit: add amend suboption to --fixup to create amend! commit Charvi Mendiratta
2021-03-14 1:32 ` Eric Sunshine
2021-03-13 13:40 ` [PATCH v5 3/6] commit: add a reword suboption to --fixup Charvi Mendiratta
2021-03-13 13:40 ` [PATCH v5 4/6] t7500: add tests for --fixup=[amend|reword] options Charvi Mendiratta
2021-03-13 13:40 ` [PATCH v5 5/6] t3437: use --fixup with options to create amend! commit Charvi Mendiratta
2021-03-13 13:40 ` [PATCH v5 6/6] doc/git-commit: add documentation for fixup=[amend|reword] options Charvi Mendiratta
2021-03-14 1:10 ` Eric Sunshine
2021-03-14 13:57 ` Charvi Mendiratta
2021-03-15 7:54 ` [PATCH v6 0/6][Outreachy] commit: Implementation of "amend!" commit Charvi Mendiratta
2021-03-19 0:52 ` Junio C Hamano
2021-03-19 3:16 ` Eric Sunshine
2021-03-19 14:10 ` Charvi Mendiratta
2021-03-15 7:54 ` [PATCH v6 1/6] sequencer: export and rename subject_length() Charvi Mendiratta
2021-03-15 7:54 ` [PATCH v6 2/6] commit: add amend suboption to --fixup to create amend! commit Charvi Mendiratta
2021-03-15 7:54 ` [PATCH v6 3/6] commit: add a reword suboption to --fixup Charvi Mendiratta
2021-03-15 7:54 ` [PATCH v6 4/6] t7500: add tests for --fixup=[amend|reword] options Charvi Mendiratta
2021-03-15 7:54 ` [PATCH v6 5/6] t3437: use --fixup with options to create amend! commit Charvi Mendiratta
2021-03-15 7:54 ` [PATCH v6 6/6] doc/git-commit: add documentation for fixup=[amend|reword] options Charvi Mendiratta
2021-03-10 19:43 ` [PATCH v4 1/6] sequencer: export and rename subject_length() Charvi Mendiratta
2021-03-10 19:43 ` [PATCH v4 2/6] commit: add amend suboption to --fixup to create amend! commit Charvi Mendiratta
2021-03-11 6:25 ` Eric Sunshine
2021-03-11 15:24 ` Charvi Mendiratta
2021-03-11 17:07 ` Eric Sunshine
2021-03-11 17:51 ` Charvi Mendiratta
2021-03-14 2:25 ` Junio C Hamano
2021-03-14 13:58 ` Charvi Mendiratta
2021-03-14 22:43 ` Junio C Hamano
2021-03-14 23:07 ` Eric Sunshine
2021-03-15 7:59 ` Charvi Mendiratta
2021-03-15 8:16 ` Eric Sunshine
2021-03-15 9:35 ` Charvi Mendiratta
2021-03-10 19:43 ` [PATCH v4 3/6] commit: add a reword suboption to --fixup Charvi Mendiratta
2021-03-11 0:31 ` Junio C Hamano
2021-03-11 4:01 ` Charvi Mendiratta
2021-03-11 5:37 ` Junio C Hamano
2021-03-11 6:37 ` Eric Sunshine
2021-03-11 15:23 ` Charvi Mendiratta
2021-03-10 19:43 ` [PATCH v4 4/6] t7500: add tests for --fixup=[amend|reword] options Charvi Mendiratta
2021-03-10 19:43 ` [PATCH v4 5/6] t3437: use --fixup with options to create amend! commit Charvi Mendiratta
2021-03-10 19:43 ` [PATCH v4 6/6] doc/git-commit: add documentation for fixup=[amend|reword] options Charvi Mendiratta
2021-03-11 0:30 ` Junio C Hamano
2021-03-11 4:02 ` Charvi Mendiratta
2021-03-11 7:48 ` Eric Sunshine
2021-03-11 15:24 ` Charvi Mendiratta [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=CAPSFM5d7wAdh1mHZkVeRrTY3iLEqejSVDA9V-Nxb72f+eqcOcA@mail.gmail.com \
--to=charvi077@gmail.com \
--cc=chriscool@tuxfamily.org \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=phillip.wood@dunelm.org.uk \
--cc=sunshine@sunshineco.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).