git/list[1] front-page[2] threads[3] people[4] search[5] about
 

On-branch topic description support?

From
Junio C Hamano <gitster@pobox.com>
Date
Jul 20, 2022, 23:40 UTC
Message-ID
<xmqqilnr1hff.fsf@gitster.g>

I've been playing with this idea from time to time, but recently I started seeing a related discussion on the b4 front, so I thought I would throw it out and how people would think.

We made "git merge" not to silently commit the result, but open the editor to encourage the integrator to describe what the topic is about. We also made "git format-patch" prepare [PATCH 0/n] aka "cover letter" so that the author of the patch series can express what the overall topic is about. What the author should say in the cover letter very much overlaps what the integrator wants to have in the log message of the commit that merges the topic to the integration branch.

But there are two (and half) links from format-patch to that merge commit that are missing.

 - You cannot prepare the cover letter material while working on the
   topic---instead, you have to write one by editing the output from
   "format-patch --cover-letter";
 - "git am" at the receiving end discards the cover letter when
   queuing the e-mailed patches to a topic.
 - "git merge" cannot take advantage of the cover letter that was
   discarded when the topic was queued.
So, here is how I would imagine a slightly better world may work.
 * When you are almost finished with the initial draft of your
   topic, you'd write a cover letter, and record it as the log
   message of an empty commit at the tip of the topic.  As you go on
   polishing the topic with "rebase -i", the empty commit would be
   kept (if we currently lose an empty commit by default, we may
   need to teach "rebase -i" to special case an empty commit at the
   tip of the range to make this convenient to use), and you would
   keep it up to date as you update the topic.
 * "git format-patch" would notice that the topic has such an empty
   commit at the tip, and use the log message from it to
   pre-populate the cover letter.
 * "git am" would learn an option to save the cover letter [0/n] and
   create such an empty commit at the tip of the branch.
 * "git merge" would learn an option to recognize that the branch
   being merged has such an empty commit at the tip, and instead
   merge the parent of the tip of the branch into the integration
   branch, while using the log message of the discarded tip commit
   in the log message of the merge itself.

Yes, there is "git config branch.mytopic.description" that helps when pre-populating the cover letter, but that only helps at the origin, and it is not shared between your personal repositories. If you have the draft of the cover letter as part of the branch, you can push/fetch them around just like all the "real" commits you are working on.

Regardless of where the cover letter comes from, the changes to "am" and "merge" dreamed above in this message would be useful, and that is the primary reason why I am envisioning that right at the origin having the topic description as an empty commit at the tip would be the most convenient. It would match the shape of the history at the author side and at the side who runs "git am".

Next: Shaoxuan Yuan
Message 1 of 25 in “On-branch topic description support?”
  1. Junio C HamanoJul 20, 2022
  2. Shaoxuan YuanJul 21, 2022
  3. Elijah NewrenJul 21, 2022
  4. Junio C HamanoJul 21, 2022
  5. Konstantin RyabitsevJul 21, 2022
  6. Philip OakleyJul 21, 2022
  7. Junio C HamanoJul 21, 2022
  8. Junio C HamanoJul 21, 2022
  9. rsbecker@nexbridge.comJul 21, 2022
  10. Konstantin RyabitsevJul 21, 2022
  11. rsbecker@nexbridge.comJul 21, 2022
  12. Ævar Arnfjörð BjarmasonJul 21, 2022
  13. Konstantin RyabitsevJul 21, 2022
  14. Junio C HamanoJul 21, 2022
  15. Ævar Arnfjörð BjarmasonJul 21, 2022
  16. Junio C HamanoJul 21, 2022
  17. Ævar Arnfjörð BjarmasonJul 21, 2022
  18. Junio C HamanoJul 21, 2022
  19. Konstantin RyabitsevJul 21, 2022
  20. Ævar Arnfjörð BjarmasonJul 21, 2022
  21. Konstantin RyabitsevJul 21, 2022
  22. Junio C HamanoJul 21, 2022
  23. Konstantin RyabitsevJul 21, 2022
  24. Junio C HamanoJul 21, 2022
  25. Bagas SanjayaJul 22, 2022

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.