branch description as a note?

branch description as a note?

[Bence Ferdinandy]

Hi,

so I've been wondering about branch descriptions being just a local
configuration. The only use-case I know for them is generating cover letters
and request-pull, although I could imagine maybe the maintainer uses branch
descriptions for storing the - well - branch descriptions for the "What's
cooking" emails and the merge commit messages. 

Now my problem with the description being a local configuration, is that
I often work on patches on two different computers. I can easily share my patch
notes with myself, but not the branch description. If these could be pushed and
fetched like a note, I think that would open up some other nice possibilities
as well, like having a standard place for MR/PR messages for forges, sharing
proposed merge commit messages, maybe other things.

For my personal issue of sharing branch descriptions with myself, I could
probably just make up a convention for myself, say using refs/notes/branches,
but it would be nice to have this built in, instead of the local config branch
description.

From usage perspective I could imagine a new `--branch` flag for notes, which
would tell `git notes` to operate on notes attached to branches instead of
specific commits, probably stored under refs/notes/branches by default. Maybe
add an `--edit-branch-note` to `git branch`. And of course have the option to
use this note instead of the description configuration wherever it makes sense.

What do you think?

Thanks,
Bence

Re: branch description as a note?

[Junio C Hamano]

"Bence Ferdinandy" <bence@ferdinandy.com> writes:

> so I've been wondering about branch descriptions being just a local
> configuration. The only use-case I know for them is generating cover letters
> and request-pull, although I could imagine maybe the maintainer uses branch
> descriptions for storing the - well - branch descriptions for the "What's
> cooking" emails and the merge commit messages. 

FWIW, that is not how I maintain "What's cooking".  Rather, the next
issue os "What's cooking" is pretty much edited manually, plus a
tool that notices when an existing topic advances in order to insert
these "(merged to 'next' on such and such day)" lines and turn '-'
bullets into '+', and move topics from other sections to 'graduated'
section.  Especially when writing comments on a topic, being able to
read about other topics (which may be related) and the list of titles
helps a lot.

There may be folks who find branch descriptions a useful way to keep
a quick reminder about the branch.  I was also hoping it may be like
so, but I seem to have failed to exploit it as a useful component in
my workflow.

> Now my problem with the description being a local configuration, is that
> I often work on patches on two different computers. I can easily share my patch
> notes with myself, but not the branch description. If these could be pushed and
> fetched like a note, I think that would open up some other nice possibilities
> as well, like having a standard place for MR/PR messages for forges, sharing
> proposed merge commit messages, maybe other things.

If this is about draft work, I would use an empty commit at the tip
of the branch.

> For my personal issue of sharing branch descriptions with myself, I could
> probably just make up a convention for myself, say using refs/notes/branches,
> but it would be nice to have this built in, instead of the local config branch
> description.
>
> From usage perspective I could imagine a new `--branch` flag for notes, which
> would tell `git notes` to operate on notes attached to branches instead of
> specific commits, probably stored under refs/notes/branches by default. Maybe
> add an `--edit-branch-note` to `git branch`. And of course have the option to
> use this note instead of the description configuration wherever it makes sense.
>
> What do you think?

The notes tree is a hashmap that uses object names as the key.  The
point of a branch is that it can grow by accumulating new commits on
it, or its commits rewritten with "rebase -i", and there are branches
with more than one commit.  So to what commit on the branch would you
hang such a note on?

Re: branch description as a note?

[Justin Tobler]

On 24/12/11 11:39AM, Bence Ferdinandy wrote:

> Now my problem with the description being a local configuration, is that
> I often work on patches on two different computers. I can easily share my patch
> notes with myself, but not the branch description. If these could be pushed and
> fetched like a note, I think that would open up some other nice possibilities
> as well, like having a standard place for MR/PR messages for forges, sharing
> proposed merge commit messages, maybe other things.

Recently I have started using branch descriptions to store MR/PR
messages and using a script to sync it with a forge over its web API.
This has got me thinking along the same lines. It would be nice if these
descriptions could be part of repository tree is some manner to more
easily facilitate distribution.

> For my personal issue of sharing branch descriptions with myself, I could
> probably just make up a convention for myself, say using refs/notes/branches,
> but it would be nice to have this built in, instead of the local config branch
> description.
> 
> From usage perspective I could imagine a new `--branch` flag for notes, which
> would tell `git notes` to operate on notes attached to branches instead of
> specific commits, probably stored under refs/notes/branches by default. Maybe
> add an `--edit-branch-note` to `git branch`. And of course have the option to
> use this note instead of the description configuration wherever it makes sense.
> 
> What do you think?

One problem I see with notes is they all live in a single notes tree and
are associated with individual commits. Therefore, I'm not quite sure
how a specific note could be correlated with a branch without having a
separate notes tree for each branch. Maybe the notes mechanism could be
extended to also support storing notes associated directly with a
reference in its tree? That might allow for notes to follow a reference
as it gets updated.

-Justin

Re: branch description as a note?

[Konstantin Ryabitsev]

On Thu, Dec 12, 2024 at 01:11:06AM +0900, Junio C Hamano wrote:
> > Now my problem with the description being a local configuration, is that
> > I often work on patches on two different computers. I can easily share my patch
> > notes with myself, but not the branch description. If these could be pushed and
> > fetched like a note, I think that would open up some other nice possibilities
> > as well, like having a standard place for MR/PR messages for forges, sharing
> > proposed merge commit messages, maybe other things.
> 
> If this is about draft work, I would use an empty commit at the tip
> of the branch.

I think this was discussed a while back:
https://lore.kernel.org/git/xmqqilnr1hff.fsf@gitster.g/

I think it boiled down to having a merge commit at the tip that would indicate
the base-commit of the WIP range. I still think it's an awesome idea if
something like this was natively supported by git tools.

-K

Re: branch description as a note?

[Kristoffer Haugsbakk]

On Wed, Dec 11, 2024, at 11:39, Bence Ferdinandy wrote:
> Hi,
>
> so I've been wondering about branch descriptions being just a local
> configuration. The only use-case I know for them is generating cover letters
> and request-pull, although I could imagine maybe the maintainer uses branch
> descriptions for storing the - well - branch descriptions for the "What's
> cooking" emails and the merge commit messages.
>
> Now my problem with the description being a local configuration, is that
> I often work on patches on two different computers. I can easily share my patch
> notes with myself, but not the branch description. If these could be pushed and
> fetched like a note, I think that would open up some other nice possibilities
> as well, like having a standard place for MR/PR messages for forges, sharing
> proposed merge commit messages, maybe other things.
>
> For my personal issue of sharing branch descriptions with myself, I could
> probably just make up a convention for myself, say using refs/notes/branches,
> but it would be nice to have this built in, instead of the local config branch
> description.
>
> From usage perspective I could imagine a new `--branch` flag for notes, which
> would tell `git notes` to operate on notes attached to branches instead of
> specific commits, probably stored under refs/notes/branches by default. Maybe
> add an `--edit-branch-note` to `git branch`. And of course have the option to
> use this note instead of the description configuration wherever it makes sense.

See also this project idea https://github.com/gitgitgadget/git/issues/438

Which also links to a 2019 thread.

With +CC on the participants. I hope that’s okay.

Re: branch description as a note?

[Bence Ferdinandy]

On Wed Dec 11, 2024 at 17:11, Junio C Hamano <gitster@pobox.com> wrote:
> "Bence Ferdinandy" <bence@ferdinandy.com> writes:
>
>> so I've been wondering about branch descriptions being just a local
>> configuration. The only use-case I know for them is generating cover letters
>> and request-pull, although I could imagine maybe the maintainer uses branch
>> descriptions for storing the - well - branch descriptions for the "What's
>> cooking" emails and the merge commit messages. 
>
> FWIW, that is not how I maintain "What's cooking".  Rather, the next
> issue os "What's cooking" is pretty much edited manually, plus a
> tool that notices when an existing topic advances in order to insert
> these "(merged to 'next' on such and such day)" lines and turn '-'
> bullets into '+', and move topics from other sections to 'graduated'
> section.  Especially when writing comments on a topic, being able to
> read about other topics (which may be related) and the list of titles
> helps a lot.
>
> There may be folks who find branch descriptions a useful way to keep
> a quick reminder about the branch.  I was also hoping it may be like
> so, but I seem to have failed to exploit it as a useful component in
> my workflow.
>
>> Now my problem with the description being a local configuration, is that
>> I often work on patches on two different computers. I can easily share my patch
>> notes with myself, but not the branch description. If these could be pushed and
>> fetched like a note, I think that would open up some other nice possibilities
>> as well, like having a standard place for MR/PR messages for forges, sharing
>> proposed merge commit messages, maybe other things.
>
> If this is about draft work, I would use an empty commit at the tip
> of the branch.

No, this is about storing some meta-info about a branch, somewhat similarly how
you can store meta-info about a commit in a note.

>
>> For my personal issue of sharing branch descriptions with myself, I could
>> probably just make up a convention for myself, say using refs/notes/branches,
>> but it would be nice to have this built in, instead of the local config branch
>> description.
>>
>> From usage perspective I could imagine a new `--branch` flag for notes, which
>> would tell `git notes` to operate on notes attached to branches instead of
>> specific commits, probably stored under refs/notes/branches by default. Maybe
>> add an `--edit-branch-note` to `git branch`. And of course have the option to
>> use this note instead of the description configuration wherever it makes sense.
>>
>> What do you think?
>
> The notes tree is a hashmap that uses object names as the key.  The
> point of a branch is that it can grow by accumulating new commits on
> it, or its commits rewritten with "rebase -i", and there are branches
> with more than one commit.  So to what commit on the branch would you
> hang such a note on?

Not to a commit, but to a branch. I mean I know a branch is just a reference to
a specific commit, but in this case the mapping would be from the branch's
_name_ to the note object.


-- 
bence.ferdinandy.com

Re: branch description as a note?

[Bence Ferdinandy]

On Wed Dec 11, 2024 at 18:34, Justin Tobler <jltobler@gmail.com> wrote:
> On 24/12/11 11:39AM, Bence Ferdinandy wrote:
>
>> Now my problem with the description being a local configuration, is that
>> I often work on patches on two different computers. I can easily share my patch
>> notes with myself, but not the branch description. If these could be pushed and
>> fetched like a note, I think that would open up some other nice possibilities
>> as well, like having a standard place for MR/PR messages for forges, sharing
>> proposed merge commit messages, maybe other things.
>
> Recently I have started using branch descriptions to store MR/PR
> messages and using a script to sync it with a forge over its web API.
> This has got me thinking along the same lines. It would be nice if these
> descriptions could be part of repository tree is some manner to more
> easily facilitate distribution.
>
>> For my personal issue of sharing branch descriptions with myself, I could
>> probably just make up a convention for myself, say using refs/notes/branches,
>> but it would be nice to have this built in, instead of the local config branch
>> description.
>> 
>> From usage perspective I could imagine a new `--branch` flag for notes, which
>> would tell `git notes` to operate on notes attached to branches instead of
>> specific commits, probably stored under refs/notes/branches by default. Maybe
>> add an `--edit-branch-note` to `git branch`. And of course have the option to
>> use this note instead of the description configuration wherever it makes sense.
>> 
>> What do you think?
>
> One problem I see with notes is they all live in a single notes tree and
> are associated with individual commits. Therefore, I'm not quite sure
> how a specific note could be correlated with a branch without having a
> separate notes tree for each branch. Maybe the notes mechanism could be
> extended to also support storing notes associated directly with a
> reference in its tree? That might allow for notes to follow a reference
> as it gets updated.

I haven't really looked into how this could be implemented, but somehow you'd
need to map the branch's name to the object for sure. I just thought it would
help if the user facing part would be similar to notes, maybe even the same
command just with the --branch flag to tell note that the branch name should
not be resolved to a commit first and then to the note, but rather the name
directly to a special "branch note".

Re: branch description as a note?

[Kristoffer Haugsbakk]

On Wed, Dec 11, 2024, at 21:13, Kristoffer Haugsbakk wrote:
> See also this project idea https://github.com/gitgitgadget/git/issues/438
>
> Which also links to a 2019 thread.
>
> With +CC on the participants. I hope that’s okay.

Reiterating what I wrote there

https://github.com/gitgitgadget/git/issues/438#issuecomment-2381017430

I would store all ref metadata in one ref.  Either divide it
up into files or have one structured file.  I’ve seen this idea
floating around.  I haven’t seen any purpose-built tools for it yet.

What I do right now: store all cover letters and whatever notes in an
untracked directory.  I plan to version it with a parallel Git database
(named something like `.git-mine`).

-- 
Kristoffer Haugsbakk

Re: branch description as a note?

[Bence Ferdinandy]

On Wed Dec 11, 2024 at 18:37, Konstantin Ryabitsev <konstantin@linuxfoundation.org> wrote:
> On Thu, Dec 12, 2024 at 01:11:06AM +0900, Junio C Hamano wrote:
>> > Now my problem with the description being a local configuration, is that
>> > I often work on patches on two different computers. I can easily share my patch
>> > notes with myself, but not the branch description. If these could be pushed and
>> > fetched like a note, I think that would open up some other nice possibilities
>> > as well, like having a standard place for MR/PR messages for forges, sharing
>> > proposed merge commit messages, maybe other things.
>> 
>> If this is about draft work, I would use an empty commit at the tip
>> of the branch.
>
> I think this was discussed a while back:
> https://lore.kernel.org/git/xmqqilnr1hff.fsf@gitster.g/
>
> I think it boiled down to having a merge commit at the tip that would indicate
> the base-commit of the WIP range. I still think it's an awesome idea if
> something like this was natively supported by git tools.
>
> -K

I read through the thread and it seems to me that in essence a special empty
commit was suggested to be used to a similar effect. I think instead of using
a "magic" commit directly in the DAG, it would be much cleaner to store this
separately in a special "branch note". "format-patch" and "am" could be taught
to handle it automatically. I do really like the idea of having a special
syntax in the note to that would delineate the branch description proper (which
could go into a merge commit) from respin versioning of a series.

It could also serve as a nice and built-in way of sharing information about
more permanent branches, e.g. the git project could publish via this special
branch note some of the info about next and seen, that is now somewhere in the
documentation. Forges could easily display it and it might also make it easier
to discover how a repository is structured after cloning.

Re: branch description as a note?

[Junio C Hamano]

"Bence Ferdinandy" <bence@ferdinandy.com> writes:

> Not to a commit, but to a branch. I mean I know a branch is just a reference to
> a specific commit, but in this case the mapping would be from the branch's
> _name_ to the note object.

I am not really sure if you know what you said you know above.

Notes are designed to map object names to blobs (technically you can
point at a random other objects but "notes edit" and other UI would
only work with blobs).  A branch does not have its "object name",
because it is *not* an object.

What you are saying sounds like "I know a screwdriver is not a
chisel, but a screwdriver has a flat blade-like head, so I want to
use it as a chisel".

Re: branch description as a note?

[Junio C Hamano]

Konstantin Ryabitsev <konstantin@linuxfoundation.org> writes:

>> If this is about draft work, I would use an empty commit at the tip
>> of the branch.
>
> I think this was discussed a while back:
> https://lore.kernel.org/git/xmqqilnr1hff.fsf@gitster.g/
>
> I think it boiled down to having a merge commit at the tip that would indicate
> the base-commit of the WIP range. I still think it's an awesome idea if
> something like this was natively supported by git tools.

I suspect taht Bence misunderstood some assumptions behind the above
discussion, some of which might not match the use case he has with
his "branch descriptions".

So, forgetting Bence's "branch description" for a while, let's see
if we can summarize the assumptions the older discussion had.

 1. We want to summarize what is on the branch, to help the reviewers
    and also the original developers.

 2. When the branch gets accepted to another branch that is higher
    in the food chain (e.g., an individual developer has a topic to
    improve a kernel driver for one specific hardware, the developer
    describes what they did and give the branch to the driver
    maintainer, and the topic gets merged to the driver's tree. The
    resulting merge may not yet be in Linus's tree, but from the
    original developer's point of view, the topic is "done" for
    now), a merge commit will use the "summary" created above in the
    messages of the merge commit.

 3. Once that happens, as it is etched into the merge commit, you
    cannot update the description anymore (unless you and your
    maintainer arrange to discard the merge and take an updated
    branch), and that limitation is acceptable.

The idea to use an empty commit is to make it easier to communicate
the "topic description" between the author and the maintainer.
During the development on the branch, the empty-commit that holds
the description can be updated using the common "rebase -i"
workflow.  If the empty commit were at the tip of the branch[*], we
can teach "git merge B" (or "git pull") to notice that the topic
description is in the commit B at the tip of the branch, create a
merge with B~1 instead, and when recording the merge, offer the log
message of B to help the maintainer write the log message for the
merge commit.  The e-mail based tools would need some changes (like
allowing "format-patch | am" pipeline to pass an empty commit), but
the principle is the same.

If Bence's "branch description" is for a use case where the
description need to be updated even after the branch gets
"concluded" by being merged to the upstream, that is not a use case
the topic description stored in an empty commit on branch we
discussed earlier would cover, I suspect, as the primary focus is to
make it easier to maintain in point 1. above, and finalize it in the
merge commit to describe what was merged in point 2. above.


[Footnote]

 * IIRC, there were some who preferred to make the description empty
   commit at the bottom of the series, and while it is possible to
   arrange such layout, it makes the eventual "git merge B" a lot
   more cumbersome (i.e. you'd need to rebase B onto the
   maintainer's tree, except for the bottom of the branch, and use
   the message from the now-discarded commit for the log message of
   the merge commit), and it would force developer to rebase the
   _entire_ branch every time they need to update the description.
   So I strongly prefer "description at the tip" layout, but the
   choice between bottom and tip does not affect the 3-point
   assumptions above.

Re: branch description as a note?

[Junio C Hamano]

Justin Tobler <jltobler@gmail.com> writes:

> One problem I see with notes is they all live in a single notes tree and
> are associated with individual commits. Therefore, I'm not quite sure
> how a specific note could be correlated with a branch without having a
> separate notes tree for each branch. Maybe the notes mechanism could be
> extended to also support storing notes associated directly with a
> reference in its tree? That might allow for notes to follow a reference
> as it gets updated.

The "in a single notes tree" part is easily surmountable by having
more than one (see "git notes --ref=..." option) and that indeed is
how I maintain the mapping from each commit to the message-ID the
commit comes from.

But you are absolutely correct to point out that notes are attached
to individual commits, and it becomes unwieldy once you start to
have more than one commit on the branch.  You can attempt to work it
around by enforcing a convention, like "the commit at the tip of the
branch has its descriptions", but then "git commit" that advances
the branch by one commit needs to move the notes, "git reset" to
rewind and "git branch" to repoint would need to transplant, but
then there needs ways to differenciate a forking (you are creating a
new branch from the tip of an existing branch, you do not want to
copy the old branch's description) and repointing.  It easily lead
to UI nightmare.

Abusing notes tree by storing branch name in a blob and taking the
blob object name as the key in a notes tree will absolutely not
work.  The names of branches are ephemeral and local (what I call
the ps/build branch may be called junio/ps/build by Patrick, and
both names are valid in the scope around these names), so using such
a local name as a key would make it even harder to share such notes
tree (not that "git notes merge" is a great end user experience to
begin with).

Re: branch description as a note?

[Konstantin Ryabitsev]

On Thu, Dec 12, 2024 at 10:39:37AM +0900, Junio C Hamano wrote:
> So, forgetting Bence's "branch description" for a while, let's see
> if we can summarize the assumptions the older discussion had.
> 
>  1. We want to summarize what is on the branch, to help the reviewers
>     and also the original developers.

Plus keep track of the history of the branch evolution (such as changelog
between different submissions).

>  2. When the branch gets accepted to another branch that is higher
>     in the food chain (e.g., an individual developer has a topic to
>     improve a kernel driver for one specific hardware, the developer
>     describes what they did and give the branch to the driver
>     maintainer, and the topic gets merged to the driver's tree. The
>     resulting merge may not yet be in Linus's tree, but from the
>     original developer's point of view, the topic is "done" for
>     now), a merge commit will use the "summary" created above in the
>     messages of the merge commit.

Correct, though this is a very Linux-specific example. Some of the other
projects have specific workflows restrictions that require that all commits
are linear (e.g. glibc/gcc) -- using merge commits wouldn't be suitable to
them. However, I think they are outliers in this regard.

>  3. Once that happens, as it is etched into the merge commit, you
>     cannot update the description anymore (unless you and your
>     maintainer arrange to discard the merge and take an updated
>     branch), and that limitation is acceptable.

Correct. Normally, once the maintainer accepts a patch series, no further
changes are made to its contents. The pull request set to the maintainer's
upstream (=Linus) will be accepted as-is or rejected as a whole, as a general
rule.

> The idea to use an empty commit is to make it easier to communicate
> the "topic description" between the author and the maintainer.
> During the development on the branch, the empty-commit that holds
> the description can be updated using the common "rebase -i"
> workflow.  If the empty commit were at the tip of the branch[*], we
> can teach "git merge B" (or "git pull") to notice that the topic
> description is in the commit B at the tip of the branch, create a
> merge with B~1 instead, and when recording the merge, offer the log
> message of B to help the maintainer write the log message for the
> merge commit.  The e-mail based tools would need some changes (like
> allowing "format-patch | am" pipeline to pass an empty commit), but
> the principle is the same.

Yes, and the commit would have two parents, one pointing at the previous
commit and the other pointing at the base commit, which would help the tools
identify where the series starts and ends.

> If Bence's "branch description" is for a use case where the
> description need to be updated even after the branch gets
> "concluded" by being merged to the upstream, that is not a use case
> the topic description stored in an empty commit on branch we
> discussed earlier would cover, I suspect, as the primary focus is to
> make it easier to maintain in point 1. above, and finalize it in the
> merge commit to describe what was merged in point 2. above.
> 
> 
> [Footnote]
> 
>  * IIRC, there were some who preferred to make the description empty
>    commit at the bottom of the series, and while it is possible to
>    arrange such layout, it makes the eventual "git merge B" a lot
>    more cumbersome (i.e. you'd need to rebase B onto the
>    maintainer's tree, except for the bottom of the branch, and use
>    the message from the now-discarded commit for the log message of
>    the merge commit), and it would force developer to rebase the
>    _entire_ branch every time they need to update the description.
>    So I strongly prefer "description at the tip" layout, but the
>    choice between bottom and tip does not affect the 3-point
>    assumptions above.

Right, this is what b4 does, but b4's use case is very specific in the sense
that the series will almost always be sent out to the list and then applied
from there, and never merged directly from the work branch. This *has*
happened before, notably, so this assumption does get broken.

Since the series is intended to be sent to the list, the fact that it is
continuously rebased doesn't really matter, because the commits themselves are
ephemeral and don't mean anything in the long term.

Additionally, keeping the tracking commit at the bottom of the series is just
the default strategy. There is also a way to make it live at the tip of the
series, but it has its own awkwardness that will almost certainly trip up more
newbies. If git does get a native way to use such cover letters, I will
certainly switch to that as the default.

-K

Re: branch description as a note?

[Bence Ferdinandy]

On Thu Dec 12, 2024 at 02:00, Junio C Hamano <gitster@pobox.com> wrote:
> "Bence Ferdinandy" <bence@ferdinandy.com> writes:
>
>> Not to a commit, but to a branch. I mean I know a branch is just a reference to
>> a specific commit, but in this case the mapping would be from the branch's
>> _name_ to the note object.
>
> I am not really sure if you know what you said you know above.
>
> Notes are designed to map object names to blobs (technically you can
> point at a random other objects but "notes edit" and other UI would
> only work with blobs).  A branch does not have its "object name",
> because it is *not* an object.
>
> What you are saying sounds like "I know a screwdriver is not a
> chisel, but a screwdriver has a flat blade-like head, so I want to
> use it as a chisel".

Well, what I meant is that at this point, it doesn't matter to me if it
requires building a new type of nuclear powered chisel, but it would be nice if
the handle were similar to that of the screwdriver :) I.e. a user probably
doesn't care how exactly the effect is achieved, they would just want to edit
some text that is tied to the branch, not commits.

Re: branch description as a note?

[Oswald Buddenhagen]

On Wed, Dec 11, 2024 at 11:07:55PM +0100, Kristoffer Haugsbakk wrote:
>On Wed, Dec 11, 2024, at 21:13, Kristoffer Haugsbakk wrote:
>> See also this project idea https://github.com/gitgitgadget/git/issues/438
>>
>> Which also links to a 2019 thread.
>>
>> With +CC on the participants. I hope that’s okay.
>
>Reiterating what I wrote there
>
>https://github.com/gitgitgadget/git/issues/438#issuecomment-2381017430
>
>I would store all ref metadata in one ref.  Either divide it
>up into files or have one structured file.  I’ve seen this idea
>floating around.  I haven’t seen any purpose-built tools for it yet.
>
https://wiki.qt.io/Git-gpush-scripts does exactly that, but putting a
state file into a special ref.

this script suite can be used to address bence's use case of migrating
wip state between machines, by having a git remote for the "magic" ref
space.

it's not perfect for a patch-based workflow, as i bolted it on as an
afterthought. and it could also use a github-centered mode. patches
welcome.

Re: branch description as a note?

[Bence Ferdinandy]

On Thu Dec 12, 2024 at 02:52, Junio C Hamano <gitster@pobox.com> wrote:
> Justin Tobler <jltobler@gmail.com> writes:
>
>> One problem I see with notes is they all live in a single notes tree and
>> are associated with individual commits. Therefore, I'm not quite sure
>> how a specific note could be correlated with a branch without having a
>> separate notes tree for each branch. Maybe the notes mechanism could be
>> extended to also support storing notes associated directly with a
>> reference in its tree? That might allow for notes to follow a reference
>> as it gets updated.
>
> The "in a single notes tree" part is easily surmountable by having
> more than one (see "git notes --ref=..." option) and that indeed is
> how I maintain the mapping from each commit to the message-ID the
> commit comes from.
>
> But you are absolutely correct to point out that notes are attached
> to individual commits, and it becomes unwieldy once you start to
> have more than one commit on the branch.  You can attempt to work it
> around by enforcing a convention, like "the commit at the tip of the
> branch has its descriptions", but then "git commit" that advances
> the branch by one commit needs to move the notes, "git reset" to
> rewind and "git branch" to repoint would need to transplant, but
> then there needs ways to differenciate a forking (you are creating a
> new branch from the tip of an existing branch, you do not want to
> copy the old branch's description) and repointing.  It easily lead
> to UI nightmare.
>
> Abusing notes tree by storing branch name in a blob and taking the
> blob object name as the key in a notes tree will absolutely not
> work.  The names of branches are ephemeral and local (what I call
> the ps/build branch may be called junio/ps/build by Patrick, and
> both names are valid in the scope around these names), so using such
> a local name as a key would make it even harder to share such notes
> tree (not that "git notes merge" is a great end user experience to
> begin with).

That's a fair point, that branch names are local. But if the information is
being sent over email (in a coverletter), that doesn't matter too much
(although should somebody attempt to "apply a cover letter" to a local branch
that already has completely different description applied that might cause
issues, i.e. I send the email from local development branch, but the receiving
end applies it directly on master which had a description already). During
push/pull though, the user already has a mapping between local and remote
branches, so that could be used to overcome the difference between local and
remote branch names. Though I'm probably glossing over other complications.