{"thread":{"id":"62623","subject":"branch description as a note?","startedAt":"2024-12-11T10:44:59Z","lastAt":"2024-12-12T10:57:43Z","messageCount":16,"participants":["Bence Ferdinandy","Junio C Hamano","Justin Tobler","Konstantin Ryabitsev","Kristoffer Haugsbakk","Oswald Buddenhagen"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"508966","messageId":"D68T28TFNW6N.2W0WV6WOUT6V0@ferdinandy.com","threadId":"62623","inReplyTo":null,"subject":"branch description as a note?","fromName":"Bence Ferdinandy","fromEmail":"bence@ferdinandy.com","sentAt":"2024-12-11T10:39:28Z","receivedAt":"2024-12-11T10:44:59Z","isPatch":false,"sender":{"key":"bence@ferdinandy.com","avatar":"https://avatars.githubusercontent.com/u/6343487?v=4"},"body":"Hi,\n\nso I've been wondering about branch descriptions being just a local\nconfiguration. The only use-case I know for them is generating cover letters\nand request-pull, although I could imagine maybe the maintainer uses branch\ndescriptions for storing the - well - branch descriptions for the \"What's\ncooking\" emails and the merge commit messages. \n\nNow my problem with the description being a local configuration, is that\nI often work on patches on two different computers. I can easily share my patch\nnotes with myself, but not the branch description. If these could be pushed and\nfetched like a note, I think that would open up some other nice possibilities\nas well, like having a standard place for MR/PR messages for forges, sharing\nproposed merge commit messages, maybe other things.\n\nFor my personal issue of sharing branch descriptions with myself, I could\nprobably just make up a convention for myself, say using refs/notes/branches,\nbut it would be nice to have this built in, instead of the local config branch\ndescription.\n\nFrom usage perspective I could imagine a new `--branch` flag for notes, which\nwould tell `git notes` to operate on notes attached to branches instead of\nspecific commits, probably stored under refs/notes/branches by default. Maybe\nadd an `--edit-branch-note` to `git branch`. And of course have the option to\nuse this note instead of the description configuration wherever it makes sense.\n\nWhat do you think?\n\nThanks,\nBence\n\n\n"},{"id":"508991","messageId":"xmqq4j3ai4it.fsf@gitster.g","threadId":"62623","inReplyTo":"D68T28TFNW6N.2W0WV6WOUT6V0@ferdinandy.com","subject":"Re: branch description as a note?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-12-11T16:11:06Z","receivedAt":"2024-12-11T16:11:09Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Bence Ferdinandy\" writes:\n\n> so I've been wondering about branch descriptions being just a local\n> configuration. The only use-case I know for them is generating cover letters\n> and request-pull, although I could imagine maybe the maintainer uses branch\n> descriptions for storing the - well - branch descriptions for the \"What's\n> cooking\" emails and the merge commit messages. \n\nFWIW, that is not how I maintain \"What's cooking\". Rather, the next\nissue os \"What's cooking\" is pretty much edited manually, plus a\ntool that notices when an existing topic advances in order to insert\nthese \"(merged to 'next' on such and such day)\" lines and turn '-'\nbullets into '+', and move topics from other sections to 'graduated'\nsection. Especially when writing comments on a topic, being able to\nread about other topics (which may be related) and the list of titles\nhelps a lot.\n\nThere may be folks who find branch descriptions a useful way to keep\na quick reminder about the branch. I was also hoping it may be like\nso, but I seem to have failed to exploit it as a useful component in\nmy workflow.\n\n> Now my problem with the description being a local configuration, is that\n> I often work on patches on two different computers. I can easily share my patch\n> notes with myself, but not the branch description. If these could be pushed and\n> fetched like a note, I think that would open up some other nice possibilities\n> as well, like having a standard place for MR/PR messages for forges, sharing\n> proposed merge commit messages, maybe other things.\n\nIf this is about draft work, I would use an empty commit at the tip\nof the branch.\n\n> For my personal issue of sharing branch descriptions with myself, I could\n> probably just make up a convention for myself, say using refs/notes/branches,\n> but it would be nice to have this built in, instead of the local config branch\n> description.\n>\n> From usage perspective I could imagine a new `--branch` flag for notes, which\n> would tell `git notes` to operate on notes attached to branches instead of\n> specific commits, probably stored under refs/notes/branches by default. Maybe\n> add an `--edit-branch-note` to `git branch`. And of course have the option to\n> use this note instead of the description configuration wherever it makes sense.\n>\n> What do you think?\n\nThe notes tree is a hashmap that uses object names as the key. The\npoint of a branch is that it can grow by accumulating new commits on\nit, or its commits rewritten with \"rebase -i\", and there are branches\nwith more than one commit. So to what commit on the branch would you\nhang such a note on?\n"},{"id":"508992","messageId":"ldbhbymjanp5xg4suatp2bgbnk3etkgxqivytpqzyqkmsiuotk@hnro3pu2zqtj","threadId":"62623","inReplyTo":"D68T28TFNW6N.2W0WV6WOUT6V0@ferdinandy.com","subject":"Re: branch description as a note?","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2024-12-11T17:34:10Z","receivedAt":"2024-12-11T17:36:23Z","isPatch":false,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"On 24/12/11 11:39AM, Bence Ferdinandy wrote:\n\n> Now my problem with the description being a local configuration, is that\n> I often work on patches on two different computers. I can easily share my patch\n> notes with myself, but not the branch description. If these could be pushed and\n> fetched like a note, I think that would open up some other nice possibilities\n> as well, like having a standard place for MR/PR messages for forges, sharing\n> proposed merge commit messages, maybe other things.\n\nRecently I have started using branch descriptions to store MR/PR\nmessages and using a script to sync it with a forge over its web API.\nThis has got me thinking along the same lines. It would be nice if these\ndescriptions could be part of repository tree is some manner to more\neasily facilitate distribution.\n\n> For my personal issue of sharing branch descriptions with myself, I could\n> probably just make up a convention for myself, say using refs/notes/branches,\n> but it would be nice to have this built in, instead of the local config branch\n> description.\n> \n> From usage perspective I could imagine a new `--branch` flag for notes, which\n> would tell `git notes` to operate on notes attached to branches instead of\n> specific commits, probably stored under refs/notes/branches by default. Maybe\n> add an `--edit-branch-note` to `git branch`. And of course have the option to\n> use this note instead of the description configuration wherever it makes sense.\n> \n> What do you think?\n\nOne problem I see with notes is they all live in a single notes tree and\nare associated with individual commits. Therefore, I'm not quite sure\nhow a specific note could be correlated with a branch without having a\nseparate notes tree for each branch. Maybe the notes mechanism could be\nextended to also support storing notes associated directly with a\nreference in its tree? That might allow for notes to follow a reference\nas it gets updated.\n\n-Justin\n"},{"id":"508993","messageId":"sem23vxg5c3xc62wvy5qn6gvoh6hc6m75mx35zgwsdyw36oexm@ayfez6uqghtt","threadId":"62623","inReplyTo":"xmqq4j3ai4it.fsf@gitster.g","subject":"Re: branch description as a note?","fromName":"Konstantin Ryabitsev","fromEmail":"konstantin@linuxfoundation.org","sentAt":"2024-12-11T17:37:35Z","receivedAt":"2024-12-11T17:37:38Z","isPatch":false,"sender":{"key":"konstantin@linuxfoundation.org","avatar":"https://gravatar.com/avatar/7cb8827c6de56e1bd2dea16508c6708aa43feed3bf3813bcdacecdf96ceadd79?d=mp&s=160"},"body":"On Thu, Dec 12, 2024 at 01:11:06AM +0900, Junio C Hamano wrote:\n> > Now my problem with the description being a local configuration, is that\n> > I often work on patches on two different computers. I can easily share my patch\n> > notes with myself, but not the branch description. If these could be pushed and\n> > fetched like a note, I think that would open up some other nice possibilities\n> > as well, like having a standard place for MR/PR messages for forges, sharing\n> > proposed merge commit messages, maybe other things.\n> \n> If this is about draft work, I would use an empty commit at the tip\n> of the branch.\n\nI think this was discussed a while back:\nhttps://lore.kernel.org/git/xmqqilnr1hff.fsf@gitster.g/\n\nI think it boiled down to having a merge commit at the tip that would indicate\nthe base-commit of the WIP range. I still think it's an awesome idea if\nsomething like this was natively supported by git tools.\n\n-K\n"},{"id":"508997","messageId":"4e8d3a75-0128-4d03-a429-59b7588f80b4@app.fastmail.com","threadId":"62623","inReplyTo":"D68T28TFNW6N.2W0WV6WOUT6V0@ferdinandy.com","subject":"Re: branch description as a note?","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2024-12-11T20:13:19Z","receivedAt":"2024-12-11T20:14:37Z","isPatch":false,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Wed, Dec 11, 2024, at 11:39, Bence Ferdinandy wrote:\n> Hi,\n>\n> so I've been wondering about branch descriptions being just a local\n> configuration. The only use-case I know for them is generating cover letters\n> and request-pull, although I could imagine maybe the maintainer uses branch\n> descriptions for storing the - well - branch descriptions for the \"What's\n> cooking\" emails and the merge commit messages.\n>\n> Now my problem with the description being a local configuration, is that\n> I often work on patches on two different computers. I can easily share my patch\n> notes with myself, but not the branch description. If these could be pushed and\n> fetched like a note, I think that would open up some other nice possibilities\n> as well, like having a standard place for MR/PR messages for forges, sharing\n> proposed merge commit messages, maybe other things.\n>\n> For my personal issue of sharing branch descriptions with myself, I could\n> probably just make up a convention for myself, say using refs/notes/branches,\n> but it would be nice to have this built in, instead of the local config branch\n> description.\n>\n> From usage perspective I could imagine a new `--branch` flag for notes, which\n> would tell `git notes` to operate on notes attached to branches instead of\n> specific commits, probably stored under refs/notes/branches by default. Maybe\n> add an `--edit-branch-note` to `git branch`. And of course have the option to\n> use this note instead of the description configuration wherever it makes sense.\n\nSee also this project idea https://github.com/gitgitgadget/git/issues/438\n\nWhich also links to a 2019 thread.\n\nWith +CC on the participants. I hope that’s okay.\n"},{"id":"509001","messageId":"D697HA5ZDN2K.1I643FREX8WKC@ferdinandy.com","threadId":"62623","inReplyTo":"xmqq4j3ai4it.fsf@gitster.g","subject":"Re: branch description as a note?","fromName":"Bence Ferdinandy","fromEmail":"bence@ferdinandy.com","sentAt":"2024-12-11T21:57:22Z","receivedAt":"2024-12-11T21:57:55Z","isPatch":false,"sender":{"key":"bence@ferdinandy.com","avatar":"https://avatars.githubusercontent.com/u/6343487?v=4"},"body":"\nOn Wed Dec 11, 2024 at 17:11, Junio C Hamano wrote:\n> \"Bence Ferdinandy\" writes:\n>\n>> so I've been wondering about branch descriptions being just a local\n>> configuration. The only use-case I know for them is generating cover letters\n>> and request-pull, although I could imagine maybe the maintainer uses branch\n>> descriptions for storing the - well - branch descriptions for the \"What's\n>> cooking\" emails and the merge commit messages. \n>\n> FWIW, that is not how I maintain \"What's cooking\". Rather, the next\n> issue os \"What's cooking\" is pretty much edited manually, plus a\n> tool that notices when an existing topic advances in order to insert\n> these \"(merged to 'next' on such and such day)\" lines and turn '-'\n> bullets into '+', and move topics from other sections to 'graduated'\n> section. Especially when writing comments on a topic, being able to\n> read about other topics (which may be related) and the list of titles\n> helps a lot.\n>\n> There may be folks who find branch descriptions a useful way to keep\n> a quick reminder about the branch. I was also hoping it may be like\n> so, but I seem to have failed to exploit it as a useful component in\n> my workflow.\n>\n>> Now my problem with the description being a local configuration, is that\n>> I often work on patches on two different computers. I can easily share my patch\n>> notes with myself, but not the branch description. If these could be pushed and\n>> fetched like a note, I think that would open up some other nice possibilities\n>> as well, like having a standard place for MR/PR messages for forges, sharing\n>> proposed merge commit messages, maybe other things.\n>\n> If this is about draft work, I would use an empty commit at the tip\n> of the branch.\n\nNo, this is about storing some meta-info about a branch, somewhat similarly how\nyou can store meta-info about a commit in a note.\n\n>\n>> For my personal issue of sharing branch descriptions with myself, I could\n>> probably just make up a convention for myself, say using refs/notes/branches,\n>> but it would be nice to have this built in, instead of the local config branch\n>> description.\n>>\n>> From usage perspective I could imagine a new `--branch` flag for notes, which\n>> would tell `git notes` to operate on notes attached to branches instead of\n>> specific commits, probably stored under refs/notes/branches by default. Maybe\n>> add an `--edit-branch-note` to `git branch`. And of course have the option to\n>> use this note instead of the description configuration wherever it makes sense.\n>>\n>> What do you think?\n>\n> The notes tree is a hashmap that uses object names as the key. The\n> point of a branch is that it can grow by accumulating new commits on\n> it, or its commits rewritten with \"rebase -i\", and there are branches\n> with more than one commit. So to what commit on the branch would you\n> hang such a note on?\n\nNot to a commit, but to a branch. I mean I know a branch is just a reference to\na specific commit, but in this case the mapping would be from the branch's\n_name_ to the note object.\n\n\n-- \nbence.ferdinandy.com\n\n"},{"id":"509002","messageId":"D697LJWHRVMR.36YBMM1URT59U@ferdinandy.com","threadId":"62623","inReplyTo":"ldbhbymjanp5xg4suatp2bgbnk3etkgxqivytpqzyqkmsiuotk@hnro3pu2zqtj","subject":"Re: branch description as a note?","fromName":"Bence Ferdinandy","fromEmail":"bence@ferdinandy.com","sentAt":"2024-12-11T22:02:56Z","receivedAt":"2024-12-11T22:03:21Z","isPatch":false,"sender":{"key":"bence@ferdinandy.com","avatar":"https://avatars.githubusercontent.com/u/6343487?v=4"},"body":"\nOn Wed Dec 11, 2024 at 18:34, Justin Tobler wrote:\n> On 24/12/11 11:39AM, Bence Ferdinandy wrote:\n>\n>> Now my problem with the description being a local configuration, is that\n>> I often work on patches on two different computers. I can easily share my patch\n>> notes with myself, but not the branch description. If these could be pushed and\n>> fetched like a note, I think that would open up some other nice possibilities\n>> as well, like having a standard place for MR/PR messages for forges, sharing\n>> proposed merge commit messages, maybe other things.\n>\n> Recently I have started using branch descriptions to store MR/PR\n> messages and using a script to sync it with a forge over its web API.\n> This has got me thinking along the same lines. It would be nice if these\n> descriptions could be part of repository tree is some manner to more\n> easily facilitate distribution.\n>\n>> For my personal issue of sharing branch descriptions with myself, I could\n>> probably just make up a convention for myself, say using refs/notes/branches,\n>> but it would be nice to have this built in, instead of the local config branch\n>> description.\n>> \n>> From usage perspective I could imagine a new `--branch` flag for notes, which\n>> would tell `git notes` to operate on notes attached to branches instead of\n>> specific commits, probably stored under refs/notes/branches by default. Maybe\n>> add an `--edit-branch-note` to `git branch`. And of course have the option to\n>> use this note instead of the description configuration wherever it makes sense.\n>> \n>> What do you think?\n>\n> One problem I see with notes is they all live in a single notes tree and\n> are associated with individual commits. Therefore, I'm not quite sure\n> how a specific note could be correlated with a branch without having a\n> separate notes tree for each branch. Maybe the notes mechanism could be\n> extended to also support storing notes associated directly with a\n> reference in its tree? That might allow for notes to follow a reference\n> as it gets updated.\n\nI haven't really looked into how this could be implemented, but somehow you'd\nneed to map the branch's name to the object for sure. I just thought it would\nhelp if the user facing part would be similar to notes, maybe even the same\ncommand just with the --branch flag to tell note that the branch name should\nnot be resolved to a commit first and then to the note, but rather the name\ndirectly to a special \"branch note\".\n\n"},{"id":"509003","messageId":"07e3a0a3-7551-4f54-bc3c-afd8dae7da02@app.fastmail.com","threadId":"62623","inReplyTo":"4e8d3a75-0128-4d03-a429-59b7588f80b4@app.fastmail.com","subject":"Re: branch description as a note?","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2024-12-11T22:07:55Z","receivedAt":"2024-12-11T22:08:17Z","isPatch":false,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Wed, Dec 11, 2024, at 21:13, Kristoffer Haugsbakk wrote:\n> See also this project idea https://github.com/gitgitgadget/git/issues/438\n>\n> Which also links to a 2019 thread.\n>\n> With +CC on the participants. I hope that’s okay.\n\nReiterating what I wrote there\n\nhttps://github.com/gitgitgadget/git/issues/438#issuecomment-2381017430\n\nI would store all ref metadata in one ref. Either divide it\nup into files or have one structured file. I’ve seen this idea\nfloating around. I haven’t seen any purpose-built tools for it yet.\n\nWhat I do right now: store all cover letters and whatever notes in an\nuntracked directory. I plan to version it with a parallel Git database\n(named something like `.git-mine`).\n\n-- \nKristoffer Haugsbakk\n"},{"id":"509004","messageId":"D697S3ZY8LBW.32P9EXVR76WBQ@ferdinandy.com","threadId":"62623","inReplyTo":"sem23vxg5c3xc62wvy5qn6gvoh6hc6m75mx35zgwsdyw36oexm@ayfez6uqghtt","subject":"Re: branch description as a note?","fromName":"Bence Ferdinandy","fromEmail":"bence@ferdinandy.com","sentAt":"2024-12-11T22:11:30Z","receivedAt":"2024-12-11T22:17:26Z","isPatch":false,"sender":{"key":"bence@ferdinandy.com","avatar":"https://avatars.githubusercontent.com/u/6343487?v=4"},"body":"\nOn Wed Dec 11, 2024 at 18:37, Konstantin Ryabitsev wrote:\n> On Thu, Dec 12, 2024 at 01:11:06AM +0900, Junio C Hamano wrote:\n>> > Now my problem with the description being a local configuration, is that\n>> > I often work on patches on two different computers. I can easily share my patch\n>> > notes with myself, but not the branch description. If these could be pushed and\n>> > fetched like a note, I think that would open up some other nice possibilities\n>> > as well, like having a standard place for MR/PR messages for forges, sharing\n>> > proposed merge commit messages, maybe other things.\n>> \n>> If this is about draft work, I would use an empty commit at the tip\n>> of the branch.\n>\n> I think this was discussed a while back:\n> https://lore.kernel.org/git/xmqqilnr1hff.fsf@gitster.g/\n>\n> I think it boiled down to having a merge commit at the tip that would indicate\n> the base-commit of the WIP range. I still think it's an awesome idea if\n> something like this was natively supported by git tools.\n>\n> -K\n\nI read through the thread and it seems to me that in essence a special empty\ncommit was suggested to be used to a similar effect. I think instead of using\na \"magic\" commit directly in the DAG, it would be much cleaner to store this\nseparately in a special \"branch note\". \"format-patch\" and \"am\" could be taught\nto handle it automatically. I do really like the idea of having a special\nsyntax in the note to that would delineate the branch description proper (which\ncould go into a merge commit) from respin versioning of a series.\n\nIt could also serve as a nice and built-in way of sharing information about\nmore permanent branches, e.g. the git project could publish via this special\nbranch note some of the info about next and seen, that is now somewhere in the\ndocumentation. Forges could easily display it and it might also make it easier\nto discover how a repository is structured after cloning.\n"},{"id":"509006","messageId":"xmqqseqthg0h.fsf@gitster.g","threadId":"62623","inReplyTo":"D697HA5ZDN2K.1I643FREX8WKC@ferdinandy.com","subject":"Re: branch description as a note?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-12-12T01:00:30Z","receivedAt":"2024-12-12T01:00:33Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Bence Ferdinandy\" writes:\n\n> Not to a commit, but to a branch. I mean I know a branch is just a reference to\n> a specific commit, but in this case the mapping would be from the branch's\n> _name_ to the note object.\n\nI am not really sure if you know what you said you know above.\n\nNotes are designed to map object names to blobs (technically you can\npoint at a random other objects but \"notes edit\" and other UI would\nonly work with blobs). A branch does not have its \"object name\",\nbecause it is *not* an object.\n\nWhat you are saying sounds like \"I know a screwdriver is not a\nchisel, but a screwdriver has a flat blade-like head, so I want to\nuse it as a chisel\".\n\n"},{"id":"509007","messageId":"xmqqa5d1he7a.fsf@gitster.g","threadId":"62623","inReplyTo":"sem23vxg5c3xc62wvy5qn6gvoh6hc6m75mx35zgwsdyw36oexm@ayfez6uqghtt","subject":"Re: branch description as a note?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-12-12T01:39:37Z","receivedAt":"2024-12-12T01:39:40Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Konstantin Ryabitsev writes:\n\n>> If this is about draft work, I would use an empty commit at the tip\n>> of the branch.\n>\n> I think this was discussed a while back:\n> https://lore.kernel.org/git/xmqqilnr1hff.fsf@gitster.g/\n>\n> I think it boiled down to having a merge commit at the tip that would indicate\n> the base-commit of the WIP range. I still think it's an awesome idea if\n> something like this was natively supported by git tools.\n\nI suspect taht Bence misunderstood some assumptions behind the above\ndiscussion, some of which might not match the use case he has with\nhis \"branch descriptions\".\n\nSo, forgetting Bence's \"branch description\" for a while, let's see\nif we can summarize the assumptions the older discussion had.\n\n 1. We want to summarize what is on the branch, to help the reviewers\n and also the original developers.\n\n 2. When the branch gets accepted to another branch that is higher\n in the food chain (e.g., an individual developer has a topic to\n improve a kernel driver for one specific hardware, the developer\n describes what they did and give the branch to the driver\n maintainer, and the topic gets merged to the driver's tree. The\n resulting merge may not yet be in Linus's tree, but from the\n original developer's point of view, the topic is \"done\" for\n now), a merge commit will use the \"summary\" created above in the\n messages of the merge commit.\n\n 3. Once that happens, as it is etched into the merge commit, you\n cannot update the description anymore (unless you and your\n maintainer arrange to discard the merge and take an updated\n branch), and that limitation is acceptable.\n\nThe idea to use an empty commit is to make it easier to communicate\nthe \"topic description\" between the author and the maintainer.\nDuring the development on the branch, the empty-commit that holds\nthe description can be updated using the common \"rebase -i\"\nworkflow. If the empty commit were at the tip of the branch[*], we\ncan teach \"git merge B\" (or \"git pull\") to notice that the topic\ndescription is in the commit B at the tip of the branch, create a\nmerge with B~1 instead, and when recording the merge, offer the log\nmessage of B to help the maintainer write the log message for the\nmerge commit. The e-mail based tools would need some changes (like\nallowing \"format-patch | am\" pipeline to pass an empty commit), but\nthe principle is the same.\n\nIf Bence's \"branch description\" is for a use case where the\ndescription need to be updated even after the branch gets\n\"concluded\" by being merged to the upstream, that is not a use case\nthe topic description stored in an empty commit on branch we\ndiscussed earlier would cover, I suspect, as the primary focus is to\nmake it easier to maintain in point 1. above, and finalize it in the\nmerge commit to describe what was merged in point 2. above.\n\n\n[Footnote]\n\n * IIRC, there were some who preferred to make the description empty\n commit at the bottom of the series, and while it is possible to\n arrange such layout, it makes the eventual \"git merge B\" a lot\n more cumbersome (i.e. you'd need to rebase B onto the\n maintainer's tree, except for the bottom of the branch, and use\n the message from the now-discarded commit for the log message of\n the merge commit), and it would force developer to rebase the\n _entire_ branch every time they need to update the description.\n So I strongly prefer \"description at the tip\" layout, but the\n choice between bottom and tip does not affect the 3-point\n assumptions above.\n\n"},{"id":"509008","messageId":"xmqqzfl1fz17.fsf@gitster.g","threadId":"62623","inReplyTo":"ldbhbymjanp5xg4suatp2bgbnk3etkgxqivytpqzyqkmsiuotk@hnro3pu2zqtj","subject":"Re: branch description as a note?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-12-12T01:52:36Z","receivedAt":"2024-12-12T01:52:39Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Justin Tobler writes:\n\n> One problem I see with notes is they all live in a single notes tree and\n> are associated with individual commits. Therefore, I'm not quite sure\n> how a specific note could be correlated with a branch without having a\n> separate notes tree for each branch. Maybe the notes mechanism could be\n> extended to also support storing notes associated directly with a\n> reference in its tree? That might allow for notes to follow a reference\n> as it gets updated.\n\nThe \"in a single notes tree\" part is easily surmountable by having\nmore than one (see \"git notes --ref=...\" option) and that indeed is\nhow I maintain the mapping from each commit to the message-ID the\ncommit comes from.\n\nBut you are absolutely correct to point out that notes are attached\nto individual commits, and it becomes unwieldy once you start to\nhave more than one commit on the branch. You can attempt to work it\naround by enforcing a convention, like \"the commit at the tip of the\nbranch has its descriptions\", but then \"git commit\" that advances\nthe branch by one commit needs to move the notes, \"git reset\" to\nrewind and \"git branch\" to repoint would need to transplant, but\nthen there needs ways to differenciate a forking (you are creating a\nnew branch from the tip of an existing branch, you do not want to\ncopy the old branch's description) and repointing. It easily lead\nto UI nightmare.\n\nAbusing notes tree by storing branch name in a blob and taking the\nblob object name as the key in a notes tree will absolutely not\nwork. The names of branches are ephemeral and local (what I call\nthe ps/build branch may be called junio/ps/build by Patrick, and\nboth names are valid in the scope around these names), so using such\na local name as a key would make it even harder to share such notes\ntree (not that \"git notes merge\" is a great end user experience to\nbegin with).\n\n"},{"id":"509009","messageId":"k2z27rszfw2zs3sz5f5rbxdsvv3h3b3ghrk4nbz2lgtec37wd3@tlelxyujzm5t","threadId":"62623","inReplyTo":"xmqqa5d1he7a.fsf@gitster.g","subject":"Re: branch description as a note?","fromName":"Konstantin Ryabitsev","fromEmail":"konstantin@linuxfoundation.org","sentAt":"2024-12-12T02:30:29Z","receivedAt":"2024-12-12T02:30:31Z","isPatch":false,"sender":{"key":"konstantin@linuxfoundation.org","avatar":"https://gravatar.com/avatar/7cb8827c6de56e1bd2dea16508c6708aa43feed3bf3813bcdacecdf96ceadd79?d=mp&s=160"},"body":"On Thu, Dec 12, 2024 at 10:39:37AM +0900, Junio C Hamano wrote:\n> So, forgetting Bence's \"branch description\" for a while, let's see\n> if we can summarize the assumptions the older discussion had.\n> \n> 1. We want to summarize what is on the branch, to help the reviewers\n> and also the original developers.\n\nPlus keep track of the history of the branch evolution (such as changelog\nbetween different submissions).\n\n> 2. When the branch gets accepted to another branch that is higher\n> in the food chain (e.g., an individual developer has a topic to\n> improve a kernel driver for one specific hardware, the developer\n> describes what they did and give the branch to the driver\n> maintainer, and the topic gets merged to the driver's tree. The\n> resulting merge may not yet be in Linus's tree, but from the\n> original developer's point of view, the topic is \"done\" for\n> now), a merge commit will use the \"summary\" created above in the\n> messages of the merge commit.\n\nCorrect, though this is a very Linux-specific example. Some of the other\nprojects have specific workflows restrictions that require that all commits\nare linear (e.g. glibc/gcc) -- using merge commits wouldn't be suitable to\nthem. However, I think they are outliers in this regard.\n\n> 3. Once that happens, as it is etched into the merge commit, you\n> cannot update the description anymore (unless you and your\n> maintainer arrange to discard the merge and take an updated\n> branch), and that limitation is acceptable.\n\nCorrect. Normally, once the maintainer accepts a patch series, no further\nchanges are made to its contents. The pull request set to the maintainer's\nupstream (=Linus) will be accepted as-is or rejected as a whole, as a general\nrule.\n\n> The idea to use an empty commit is to make it easier to communicate\n> the \"topic description\" between the author and the maintainer.\n> During the development on the branch, the empty-commit that holds\n> the description can be updated using the common \"rebase -i\"\n> workflow. If the empty commit were at the tip of the branch[*], we\n> can teach \"git merge B\" (or \"git pull\") to notice that the topic\n> description is in the commit B at the tip of the branch, create a\n> merge with B~1 instead, and when recording the merge, offer the log\n> message of B to help the maintainer write the log message for the\n> merge commit. The e-mail based tools would need some changes (like\n> allowing \"format-patch | am\" pipeline to pass an empty commit), but\n> the principle is the same.\n\nYes, and the commit would have two parents, one pointing at the previous\ncommit and the other pointing at the base commit, which would help the tools\nidentify where the series starts and ends.\n\n> If Bence's \"branch description\" is for a use case where the\n> description need to be updated even after the branch gets\n> \"concluded\" by being merged to the upstream, that is not a use case\n> the topic description stored in an empty commit on branch we\n> discussed earlier would cover, I suspect, as the primary focus is to\n> make it easier to maintain in point 1. above, and finalize it in the\n> merge commit to describe what was merged in point 2. above.\n> \n> \n> [Footnote]\n> \n> * IIRC, there were some who preferred to make the description empty\n> commit at the bottom of the series, and while it is possible to\n> arrange such layout, it makes the eventual \"git merge B\" a lot\n> more cumbersome (i.e. you'd need to rebase B onto the\n> maintainer's tree, except for the bottom of the branch, and use\n> the message from the now-discarded commit for the log message of\n> the merge commit), and it would force developer to rebase the\n> _entire_ branch every time they need to update the description.\n> So I strongly prefer \"description at the tip\" layout, but the\n> choice between bottom and tip does not affect the 3-point\n> assumptions above.\n\nRight, this is what b4 does, but b4's use case is very specific in the sense\nthat the series will almost always be sent out to the list and then applied\nfrom there, and never merged directly from the work branch. This *has*\nhappened before, notably, so this assumption does get broken.\n\nSince the series is intended to be sent to the list, the fact that it is\ncontinuously rebased doesn't really matter, because the commits themselves are\nephemeral and don't mean anything in the long term.\n\nAdditionally, keeping the tracking commit at the bottom of the series is just\nthe default strategy. There is also a way to make it live at the tip of the\nseries, but it has its own awkwardness that will almost certainly trip up more\nnewbies. If git does get a native way to use such cover letters, I will\ncertainly switch to that as the default.\n\n-K\n"},{"id":"509025","messageId":"D69NVGIBKYO2.R5Q7TP69X6C8@ferdinandy.com","threadId":"62623","inReplyTo":"xmqqseqthg0h.fsf@gitster.g","subject":"Re: branch description as a note?","fromName":"Bence Ferdinandy","fromEmail":"bence@ferdinandy.com","sentAt":"2024-12-12T10:48:10Z","receivedAt":"2024-12-12T10:48:37Z","isPatch":false,"sender":{"key":"bence@ferdinandy.com","avatar":"https://avatars.githubusercontent.com/u/6343487?v=4"},"body":"\nOn Thu Dec 12, 2024 at 02:00, Junio C Hamano wrote:\n> \"Bence Ferdinandy\" writes:\n>\n>> Not to a commit, but to a branch. I mean I know a branch is just a reference to\n>> a specific commit, but in this case the mapping would be from the branch's\n>> _name_ to the note object.\n>\n> I am not really sure if you know what you said you know above.\n>\n> Notes are designed to map object names to blobs (technically you can\n> point at a random other objects but \"notes edit\" and other UI would\n> only work with blobs). A branch does not have its \"object name\",\n> because it is *not* an object.\n>\n> What you are saying sounds like \"I know a screwdriver is not a\n> chisel, but a screwdriver has a flat blade-like head, so I want to\n> use it as a chisel\".\n\nWell, what I meant is that at this point, it doesn't matter to me if it\nrequires building a new type of nuclear powered chisel, but it would be nice if\nthe handle were similar to that of the screwdriver :) I.e. a user probably\ndoesn't care how exactly the effect is achieved, they would just want to edit\nsome text that is tied to the branch, not commits.\n\n\n"},{"id":"509026","messageId":"Z1q_gyUlnWiVtc7P@ugly","threadId":"62623","inReplyTo":"07e3a0a3-7551-4f54-bc3c-afd8dae7da02@app.fastmail.com","subject":"Re: branch description as a note?","fromName":"Oswald Buddenhagen","fromEmail":"oswald.buddenhagen@gmx.de","sentAt":"2024-12-12T10:48:35Z","receivedAt":"2024-12-12T10:48:55Z","isPatch":false,"sender":{"key":"oswald.buddenhagen@gmx.de","avatar":"https://avatars.githubusercontent.com/u/812380?v=4"},"body":"On Wed, Dec 11, 2024 at 11:07:55PM +0100, Kristoffer Haugsbakk wrote:\n>On Wed, Dec 11, 2024, at 21:13, Kristoffer Haugsbakk wrote:\n>> See also this project idea https://github.com/gitgitgadget/git/issues/438\n>>\n>> Which also links to a 2019 thread.\n>>\n>> With +CC on the participants. I hope that’s okay.\n>\n>Reiterating what I wrote there\n>\n>https://github.com/gitgitgadget/git/issues/438#issuecomment-2381017430\n>\n>I would store all ref metadata in one ref. Either divide it\n>up into files or have one structured file. I’ve seen this idea\n>floating around. I haven’t seen any purpose-built tools for it yet.\n>\nhttps://wiki.qt.io/Git-gpush-scripts does exactly that, but putting a\nstate file into a special ref.\n\nthis script suite can be used to address bence's use case of migrating\nwip state between machines, by having a git remote for the \"magic\" ref\nspace.\n\nit's not perfect for a patch-based workflow, as i bolted it on as an\nafterthought. and it could also use a github-centered mode. patches\nwelcome.\n"},{"id":"509028","messageId":"D69O2H3DJIH9.3L52AI25I3U3R@ferdinandy.com","threadId":"62623","inReplyTo":"xmqqzfl1fz17.fsf@gitster.g","subject":"Re: branch description as a note?","fromName":"Bence Ferdinandy","fromEmail":"bence@ferdinandy.com","sentAt":"2024-12-12T10:57:20Z","receivedAt":"2024-12-12T10:57:43Z","isPatch":false,"sender":{"key":"bence@ferdinandy.com","avatar":"https://avatars.githubusercontent.com/u/6343487?v=4"},"body":"\nOn Thu Dec 12, 2024 at 02:52, Junio C Hamano wrote:\n> Justin Tobler writes:\n>\n>> One problem I see with notes is they all live in a single notes tree and\n>> are associated with individual commits. Therefore, I'm not quite sure\n>> how a specific note could be correlated with a branch without having a\n>> separate notes tree for each branch. Maybe the notes mechanism could be\n>> extended to also support storing notes associated directly with a\n>> reference in its tree? That might allow for notes to follow a reference\n>> as it gets updated.\n>\n> The \"in a single notes tree\" part is easily surmountable by having\n> more than one (see \"git notes --ref=...\" option) and that indeed is\n> how I maintain the mapping from each commit to the message-ID the\n> commit comes from.\n>\n> But you are absolutely correct to point out that notes are attached\n> to individual commits, and it becomes unwieldy once you start to\n> have more than one commit on the branch. You can attempt to work it\n> around by enforcing a convention, like \"the commit at the tip of the\n> branch has its descriptions\", but then \"git commit\" that advances\n> the branch by one commit needs to move the notes, \"git reset\" to\n> rewind and \"git branch\" to repoint would need to transplant, but\n> then there needs ways to differenciate a forking (you are creating a\n> new branch from the tip of an existing branch, you do not want to\n> copy the old branch's description) and repointing. It easily lead\n> to UI nightmare.\n>\n> Abusing notes tree by storing branch name in a blob and taking the\n> blob object name as the key in a notes tree will absolutely not\n> work. The names of branches are ephemeral and local (what I call\n> the ps/build branch may be called junio/ps/build by Patrick, and\n> both names are valid in the scope around these names), so using such\n> a local name as a key would make it even harder to share such notes\n> tree (not that \"git notes merge\" is a great end user experience to\n> begin with).\n\nThat's a fair point, that branch names are local. But if the information is\nbeing sent over email (in a coverletter), that doesn't matter too much\n(although should somebody attempt to \"apply a cover letter\" to a local branch\nthat already has completely different description applied that might cause\nissues, i.e. I send the email from local development branch, but the receiving\nend applies it directly on master which had a description already). During\npush/pull though, the user already has a mapping between local and remote\nbranches, so that could be used to overcome the difference between local and\nremote branch names. Though I'm probably glossing over other complications.\n\n"}]}