push branch descriptions

push branch descriptions

[Angelo Borsotti]

Hi

currently, there is no means to push a branch description to a remote
repository. It is possible to create a branch, but not to set its
description.
Would not be more correct to push also branch descriptions when
branches are pushed?

-Angelo Borsotti

Re: push branch descriptions

[Ramkumar Ramachandra]

Hi,

Angelo Borsotti wrote:
> currently, there is no means to push a branch description to a remote
> repository. It is possible to create a branch, but not to set its
> description.
> Would not be more correct to push also branch descriptions when
> branches are pushed?

Branch descriptions are currently stored in .git/config (see
branch.<branchname>.description), and are hence intended to be local.
But yes, it would be nice to have it synced with the remote- I have no
clue how to make that possible though.

Ram

Re: push branch descriptions

[Michael J Gruber]

Ramkumar Ramachandra venit, vidit, dixit 14.11.2012 11:33:
> Hi,
> 
> Angelo Borsotti wrote:
>> currently, there is no means to push a branch description to a remote
>> repository. It is possible to create a branch, but not to set its
>> description.
>> Would not be more correct to push also branch descriptions when
>> branches are pushed?
> 
> Branch descriptions are currently stored in .git/config (see
> branch.<branchname>.description), and are hence intended to be local.
> But yes, it would be nice to have it synced with the remote- I have no
> clue how to make that possible though.

I find that nice, too, but back then I seemed to be the only one, "then"
being the time when I proposed (and implemented) branch notes as notes
(git notes) being attached to the (sha1 of the) branch name (or any
other refname). They are versioned/shareable/syncable just like notes
are. I had all of this working (git branch --notes display, git
format-patch --cover-letter and such); what was missing was a way to
attach/look-up notes for remote branches, which is related to our
current lack of default handling of remote notes refs. That's not a
fundamental problem, just a matter of agreeing about a proper default
setup for remote notes refs.

As I said, others preferred local branch descriptions (no git notes) in
config, and that's what is in git.git now.

Michael

Re: push branch descriptions

[Junio C Hamano]

Angelo Borsotti <angelo.borsotti@gmail.com> writes:

> currently, there is no means to push a branch description to a remote
> repository. It is possible to create a branch, but not to set its
> description.

Correct.  You have to go to the remote repository and run "git
branch --edit-description" there; there is currently no way to do
this remotely, which may be an issue, but...

> Would not be more correct to push also branch descriptions when
> branches are pushed?

... I do not think "git push" is the best place to do so, given the
inherently local nature of branches and branch descriptions.

Imagine the project creates a branch "magic" to enhance its system
with magic words.  The description for the "magic" branch in the
project may say "support magic words" or something.

You and your friend are tasked to add a handful of magic words,
e.g. "xyzzy", "frotz" and "nitfol".  You may start your work like so
on your "magic-xyzzy" branch:

    $ git clone git://example.com/zork.git/
    $ git checkout -b magic-xyzzy -t origin/magic

And you say something like "add xyzzy magic" in its branch
description.

    $ git branch --edit-description magic-xyzzy

After finishing your work, you may push it

    $ git push origin magic-xyzzy:magic

Should the description of the subtask "add xyzzy magic" overwrite
the purpose of the project wide "magic" branch "support magic words"?
Most likely not.

The local nature of the description becomes even more clear if you
imagine the case where the push at the last stage gets rejected due
to non-fast-forward error (in other words, your friend has already
pushed her support of the "frotz" magic to the "magic" branch.

In fact, you would normally not directly push your magic-xyzzy
branch to the magic branch, but you would do something like this
once you are done:

    $ git checkout -b magic -t origin/magic
    $ git pull origin ;# to update with her work
    $ git merge magic-xyzzy
    $ git push origin magic

And the last "merge" is where the description for your magic-xyzzy
is used to fill the commit log template for you to explain your
merge (that is, you are merging a branch whose description is "add
xyzzy magic").  There is no reason to propagate the description of
your magic-xyzzy topic to the description of shared magic branch
when you push, as this merge commit already records what the branch
that was merged was about.

So you could modify "git push" to set the branch description when
you push to create a branch remotely, but in general, "git push"
should not be updating the branch description with the description
of your local branch.  This comes as a consequence of the fact that
the purpose of the branch in the remote central repository is, more
often than not, different from the purpose of the corresponding
branch in your repository.

It would conceptually be a lot cleaner to treat updating of remote
branch description as a separate "repository management" class of
operation, similar to setting the repository description stored in
$GIT_DIR/description.

Re: push branch descriptions

[Angelo Borsotti]

Hi Junio,

> It would conceptually be a lot cleaner to treat updating of remote
> Ibranch description as a separate "repository management" class of
> Ioperation, similar to setting the repository description stored in
> I$GIT_DIR/description.

I agree, it should be a distinct operation. I was thinking that when
you have a remote bare repository, the normal way of adding contents
to it is to push to it, and thus also adding a description should be
done with some sort of pushing. Creating branches is also normally
done with a push (think how difficult it is to create a branch in a
bare repository when the HEAD is not set ...).

-Angelo

On 14 November 2012 14:57, Junio C Hamano <gitster@pobox.com> wrote:
> Angelo Borsotti <angelo.borsotti@gmail.com> writes:
>
>> currently, there is no means to push a branch description to a remote
>> repository. It is possible to create a branch, but not to set its
>> description.
>
> Correct.  You have to go to the remote repository and run "git
> branch --edit-description" there; there is currently no way to do
> this remotely, which may be an issue, but...
>
>> Would not be more correct to push also branch descriptions when
>> branches are pushed?
>
> ... I do not think "git push" is the best place to do so, given the
> inherently local nature of branches and branch descriptions.
>
> Imagine the project creates a branch "magic" to enhance its system
> with magic words.  The description for the "magic" branch in the
> project may say "support magic words" or something.
>
> You and your friend are tasked to add a handful of magic words,
> e.g. "xyzzy", "frotz" and "nitfol".  You may start your work like so
> on your "magic-xyzzy" branch:
>
>     $ git clone git://example.com/zork.git/
>     $ git checkout -b magic-xyzzy -t origin/magic
>
> And you say something like "add xyzzy magic" in its branch
> description.
>
>     $ git branch --edit-description magic-xyzzy
>
> After finishing your work, you may push it
>
>     $ git push origin magic-xyzzy:magic
>
> Should the description of the subtask "add xyzzy magic" overwrite
> the purpose of the project wide "magic" branch "support magic words"?
> Most likely not.
>
> The local nature of the description becomes even more clear if you
> imagine the case where the push at the last stage gets rejected due
> to non-fast-forward error (in other words, your friend has already
> pushed her support of the "frotz" magic to the "magic" branch.
>
> In fact, you would normally not directly push your magic-xyzzy
> branch to the magic branch, but you would do something like this
> once you are done:
>
>     $ git checkout -b magic -t origin/magic
>     $ git pull origin ;# to update with her work
>     $ git merge magic-xyzzy
>     $ git push origin magic
>
> And the last "merge" is where the description for your magic-xyzzy
> is used to fill the commit log template for you to explain your
> merge (that is, you are merging a branch whose description is "add
> xyzzy magic").  There is no reason to propagate the description of
> your magic-xyzzy topic to the description of shared magic branch
> when you push, as this merge commit already records what the branch
> that was merged was about.
>
> So you could modify "git push" to set the branch description when
> you push to create a branch remotely, but in general, "git push"
> should not be updating the branch description with the description
> of your local branch.  This comes as a consequence of the fact that
> the purpose of the branch in the remote central repository is, more
> often than not, different from the purpose of the corresponding
> branch in your repository.
>
> It would conceptually be a lot cleaner to treat updating of remote
> branch description as a separate "repository management" class of
> operation, similar to setting the repository description stored in
> $GIT_DIR/description.

RE: push branch descriptions

[Pyeron, Jason J CTR (US)]

[-- Attachment #1: Type: text/plain, Size: 4409 bytes --]

> -----Original Message-----
> From: Angelo Borsotti
> Sent: Wednesday, November 14, 2012 9:51 AM
> 
> Hi Junio,
> 
> > It would conceptually be a lot cleaner to treat updating of remote
> > Ibranch description as a separate "repository management" class of
> > Ioperation, similar to setting the repository description stored in
> > I$GIT_DIR/description.
> 
> I agree, it should be a distinct operation. I was thinking that when
> you have a remote bare repository, the normal way of adding contents
> to it is to push to it, and thus also adding a description should be
> done with some sort of pushing. Creating branches is also normally
> done with a push (think how difficult it is to create a branch in a
> bare repository when the HEAD is not set ...).

Only if the push were to create the branch...


> On 14 November 2012 14:57, Junio C Hamano <gitster@pobox.com> wrote:
> > Angelo Borsotti <angelo.borsotti@gmail.com> writes:
> >
> >> currently, there is no means to push a branch description to a
> remote
> >> repository. It is possible to create a branch, but not to set its
> >> description.
> >
> > Correct.  You have to go to the remote repository and run "git
> > branch --edit-description" there; there is currently no way to do
> > this remotely, which may be an issue, but...
> >
> >> Would not be more correct to push also branch descriptions when
> >> branches are pushed?
> >
> > ... I do not think "git push" is the best place to do so, given the
> > inherently local nature of branches and branch descriptions.
> >
> > Imagine the project creates a branch "magic" to enhance its system
> > with magic words.  The description for the "magic" branch in the
> > project may say "support magic words" or something.
> >
> > You and your friend are tasked to add a handful of magic words,
> > e.g. "xyzzy", "frotz" and "nitfol".  You may start your work like so
> > on your "magic-xyzzy" branch:
> >
> >     $ git clone git://example.com/zork.git/
> >     $ git checkout -b magic-xyzzy -t origin/magic

And here the branch description should copy from origin/magic.

> >
> > And you say something like "add xyzzy magic" in its branch
> > description.
> >
> >     $ git branch --edit-description magic-xyzzy
> >

And now it is edited

> > After finishing your work, you may push it
> >
> >     $ git push origin magic-xyzzy:magic
> >
> > Should the description of the subtask "add xyzzy magic" overwrite
> > the purpose of the project wide "magic" branch "support magic words"?
> > Most likely not.

Never overwrite anything.

> >
> > The local nature of the description becomes even more clear if you
> > imagine the case where the push at the last stage gets rejected due
> > to non-fast-forward error (in other words, your friend has already
> > pushed her support of the "frotz" magic to the "magic" branch.
> >
> > In fact, you would normally not directly push your magic-xyzzy
> > branch to the magic branch, but you would do something like this
> > once you are done:
> >
> >     $ git checkout -b magic -t origin/magic
> >     $ git pull origin ;# to update with her work
> >     $ git merge magic-xyzzy
> >     $ git push origin magic
> >
> > And the last "merge" is where the description for your magic-xyzzy
> > is used to fill the commit log template for you to explain your
> > merge (that is, you are merging a branch whose description is "add
> > xyzzy magic").  There is no reason to propagate the description of
> > your magic-xyzzy topic to the description of shared magic branch
> > when you push, as this merge commit already records what the branch
> > that was merged was about.
> >
> > So you could modify "git push" to set the branch description when
> > you push to create a branch remotely, but in general, "git push"
> > should not be updating the branch description with the description
> > of your local branch.  This comes as a consequence of the fact that
> > the purpose of the branch in the remote central repository is, more
> > often than not, different from the purpose of the corresponding
> > branch in your repository.
> >

But pulling such into a new branch should copy the description (unless explicitly set)

> > It would conceptually be a lot cleaner to treat updating of remote
> > branch description as a separate "repository management" class of
> > operation, similar to setting the repository description stored in
> > $GIT_DIR/description.


[-- Attachment #2: smime.p7s --]
[-- Type: application/x-pkcs7-signature, Size: 5615 bytes --]

Re: push branch descriptions

[Junio C Hamano]

"Pyeron, Jason J CTR (US)" <jason.j.pyeron.ctr@mail.mil> writes:

>> > Imagine the project creates a branch "magic" to enhance its system
>> > with magic words.  The description for the "magic" branch in the
>> > project may say "support magic words" or something.
>> >
>> > You and your friend are tasked to add a handful of magic words,
>> > e.g. "xyzzy", "frotz" and "nitfol".  You may start your work like so
>> > on your "magic-xyzzy" branch:
>> >
>> >     $ git clone git://example.com/zork.git/
>> >     $ git checkout -b magic-xyzzy -t origin/magic
>
> And here the branch description should copy from origin/magic.

I doubt it should.  The purpose of the "magic" branch at the remote
in my example were to "support magic words" (without limiting which
magic words the project wants to support) and that is what the
description over there may say, while the purpose of the local
"magic-xyzzy" branch you create in order to add the support for
"xyzzy" magic is just one small subtask of it.

That is what I meant by "the inherently local nature of the branches
and branch descriptions".  Git as a distributed system works well
exactly because what each repository has is inherently local, and
people can do whatever they want in their own repositories, while
allowing collaboration among participants by pulling and pushing
histories that share compatible (note: not necessarily "identical")
goals.  "support magic words" being a superset of "add xyzzy magic"
is an example of this principle.  They have different goals (and
that is why propagating the description of your "magic-xyzzy" to the
project global "magic" is a wrong thing to do), but from the point
of view of the project global "magic" branch, what your "magic-xyzzy"
branch wanted to do is compatible with its larger goal (and that is
why merging to "magic" from "magic-xyzzy" is a good thing, while
merging the other way is frowned upon in general).