Decoding git show-branch output

Decoding git show-branch output

[Bill Lear]

If this is an inappropriate forum for this question, please let me know
and I will redirect it elsewhere.

We have converted from cvs to git recently and one of our developers
seems to have made a terrific mess of things.

He is seeing "fatal: protocol error: bad line length character" when
pushing from a one of his work repositories to our main company
repository.  He is seeing his git merges vanish (he can't find his
code where he thinks it should be) and is apparently having trouble
doing things we thought should be very simple.  Personally, I have
had little trouble with git, but now I'm trying to figure out what
it was he has done to get himself in this mess.

We are running the latest git 1.4.4.1, under Linux (a few flavors,
Centos 4.3, Redhat 4, etc.).  Our company repository is on Fedora Core
6.

I thought I would use git-show-branch to try to unravel some of this
mystery.

After doing several commits, our company repository looks like this:

% GIT_DIR=fus git-show-branch --more=20 --topo-order
[master] Merge branch 'master' of source:/repos/git/fus
[master^2] Add more timing of Tbar components.
[master^2^] Add more timing of Tbar components.
[master^] Tell git to ignore more stuff.
[master~2] fix to pass on gcc
[master~3] Merge branch 'master' of ssh+git://source/repos/git/fus
[master~3^2] Merge branch 'master' of source:/repos/git/fus
[master~3^2^2] placeholders for 1.0 release
[master~3^2^] recursive_binomial branch merged to master.
[master~3^2~2] More Tbar timing statistics.
[master~4] with this you will be able to do help on any command
[master~5] help for commands
[master~6] add echo to try and track down intermittent failure
[master~7] fix stupid typo
[master~8] fix stupid error
[master~9] add removal of files to prevent affecting future test runs
[master~10] Merge branch 'master' of ssh+git://source/repos/git/fus
[master~10^2] Merge branch 'master' of ssh+git://source/repos/git/fus
[master~10^2^] update to report output when gen_run.tcl fails
[master~11] Merge branch 'master' of ssh+git://source/repos/git/fus
[master~10^2^2] Integer type fixups to suppress warnings.

I'm very confused by the syntax above.  What does "[master^2^]" mean?
Ditto with things like "[master~3^2^2]" and "[master~3^2~2]".  Why
is the order 

[master]
[master^2]
[master^2^]
[master^]

?  I would have thought [master] would be followed by [master^], not
[master^2].  Obviously I'm confused.

I have read the May 2006 article in Linux Magazine, "Embrace The Git
Index" by Jon Loeliger, and tried to make sense of the "HOW TO READ
COMMIT SHORT-HAND NAMES" box on the sixth page, but can't seem to.

I'm used to visual representations that show things in chronological order,
from left to right, say as

                                   H---I---J  second
                                  /
                         E---F---G---K---L  first
                        /
                       /       O---P---Q  third
                      /       /
         A---B---C---D---M---N  master

or:

                                   H---I---J  second
                                  /         \
                         E---F---G---K---L---R  first
                        /                     \
                       /       O---P---Q  third \
                      /       /         \         \
         A---B---C---D---M---N-----------S---------T  master

(third merged onto master, second onto first, first onto master)

But I can't seem to make the mental leap to map the show-branch output
to something I understand such as the above.

So, If someone could help me grok this, I'd appreciate it.

Again, apologies if this is not the appropriate forum.


Bill

Re: Decoding git show-branch output

[Santi Béjar]

On 1/19/07, Bill Lear <rael@zopyra.com> wrote:

[...]

> I'm very confused by the syntax above.  What does "[master^2^]" mean?
> Ditto with things like "[master~3^2^2]" and "[master~3^2~2]".

They explain the relation between commits:

^ -> first parent
^n -> n-th parent
~n -> <n>th generation parent, following only the first parent.

See the manual page of git-rev-parse (or the tutorial for some simple examples).

>  Why is the order
>
> [master]
> [master^2]
> [master^2^]
> [master^]
>
> ?  I would have thought [master] would be followed by [master^], not
> [master^2].  Obviously I'm confused.

The order of the parents is not important.

> I'm used to visual representations that show things in chronological order,
> from left to right, say as
>
>                                    H---I---J  second
>                                   /
>                          E---F---G---K---L  first
>                         /
>                        /       O---P---Q  third
>                       /       /
>          A---B---C---D---M---N  master
>
> or:
>
>                                    H---I---J  second
>                                   /         \
>                          E---F---G---K---L---R  first
>                         /                     \
>                        /       O---P---Q  third \
>                       /       /         \         \
>          A---B---C---D---M---N-----------S---------T  master
>
> (third merged onto master, second onto first, first onto master)
>

Then, use gitk to visualize the graph.

> Again, apologies if this is not the appropriate forum.

Your are welcome.

Santi

Re: Decoding git show-branch output

[Bill Lear]

On Friday, January 19, 2007 at 15:13:30 (+0100) Santi Béjar writes:
>On 1/19/07, Bill Lear <rael@zopyra.com> wrote:
>
>[...]
>
>> I'm very confused by the syntax above.  What does "[master^2^]" mean?
>> Ditto with things like "[master~3^2^2]" and "[master~3^2~2]".
>
>They explain the relation between commits:
>
>^ -> first parent
>^n -> n-th parent
>~n -> <n>th generation parent, following only the first parent.
>
>See the manual page of git-rev-parse (or the tutorial for some simple examples).

I did.  Still don't understand.  So, following your explanation,

master~3 ^2 ~2

Means the 2nd (first generation) parent of the second parent of the
3rd (first generation) parent?  Is there a way to simply state this in
plain words, say in terms of commits/merges?  I'm unsure how to
interpret the above, especially since none of us has been developing
on a branch (I see no other branch names except master, also).

I'm currently running qgit/gitk to try to figure this all out.  It
appears that somehow we generated way more branches than we thought we
were.

Our basic work-flow for a developer is to set up one or more "private"
repositories on our machines, by issuing a git-clone of our company repo.

Then we set up a "public" repo on our machine by issuing a "git --bare
init-db --shared".  We then push into this repo when ready, and from
there other developers pull.

Then, it seems that we push to our company repository both from our
private repos and our public ones, as we see fit.

I'm not sure if this is sane: is it ok to clone the company repo,
then push from that clone into a bare repo, then from there to
the company one?  Is git doing some sort of weird, silent pseudo-merge
that we don't understand, thus generated what appears to be a very
tangled, albeit brief, history, when we examine it?

I have read about 8 documents on git, experimented with it
extensively, and, at our company, I am arguably the "git expert"; I
thought that I had done all of my work on my local repo's master
branch, and only pushed from that branch up to our company repo.  Yet,
qgit shows that one of my first commits (to fix a few simply typos in
documentation) goes off onto another branch.  git-show-branch shows
"[master~3^2~9] Fix a few typos" for this.  I'm very confused how this
could have happened, and I want to ensure we are doing things in a way
that is predictable...

Thank you again.


Bill

Re: Decoding git show-branch output

[Jakub Narebski]

[Cc: git@vger.kernel.org]

Bill Lear wrote:

> I'm not sure if this is sane: is it ok to clone the company repo,
> then push from that clone into a bare repo, then from there to
> the company one?  Is git doing some sort of weird, silent pseudo-merge
> that we don't understand, thus generated what appears to be a very
> tangled, albeit brief, history, when we examine it?

It is quite sane, I think, to use bare repositories as "gateways".
 
> I have read about 8 documents on git, experimented with it
> extensively, and, at our company, I am arguably the "git expert"; I
> thought that I had done all of my work on my local repo's master
> branch, and only pushed from that branch up to our company repo.  Yet,
> qgit shows that one of my first commits (to fix a few simply typos in
> documentation) goes off onto another branch.  git-show-branch shows
> "[master~3^2~9] Fix a few typos" for this.  I'm very confused how this
> could have happened, and I want to ensure we are doing things in a way
> that is predictable...

Nether push nor fetch does do merges. What can do merges (if not in
fast-forward case, i.e. in case where only one side did any changes), is
pull (but it doesn;t do this silently). I suspect that pulling from
different repositories (probably into different tracking branches, or
without use of tracking branches) might be the culprit.

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Decoding git show-branch output

[Junio C Hamano]

Bill Lear <rael@zopyra.com> writes:

> master~3 ^2 ~2
>
> Means the 2nd (first generation) parent of the second parent of the
> 3rd (first generation) parent?  Is there a way to simply state this in
> plain words, say in terms of commits/merges?

You had one commit (master~3^2~2).  You built one commit on top
of it (master~3^2~1) and another (master~3^2).

That one was merged into something else as the second parent,
and the merge result is master~3 (that "something else" is
master~4 aka master~3^ aka master~3^1).

You built three commits on top of that, and that is where your
master currently is.

> I'm unsure how to
> interpret the above, especially since none of us has been developing
> on a branch (I see no other branch names except master, also).

But you are.  Each repository are independent and the branches
your developers have, even though each of them have only one,
are separate branches.  You are exercising the distributedness
of git development model.

> I'm not sure if this is sane: is it ok to clone the company repo,
> then push from that clone into a bare repo, then from there to
> the company one?

That's essentially everybody doing distributed development does
in git land -- it is very sane.

> Is git doing some sort of weird, silent pseudo-merge
> that we don't understand, thus generated what appears to be a very
> tangled, albeit brief, history, when we examine it?

I do not think so, but the person creating a commit may first be
pulling from the central location, which needs a merge and
results in one.  That's very common in centralized workflow
modelled after how CVS is used.

Let's say you have the central (perhaps bare but it does not
matter if it is bare or not) repository and two workers, Alice
and Bob.  They both clone from it and make one commit each in
their repositories.  The commit ancestries in the entire world
would look like this:

          .---o Alice's 'master'
         /
 ---o---o-------o Bob's 'master'
        ^
        central repo's 'master'

Then Bob pushes to the central repo.  Since it is a
fast-forward, his push is accpeted and the picture would become
like this:

          .---o Alice's 'master'
         /
 ---o---o-------o Bob's 'master'
                ^
                central repo's 'master'

When Alice wants to push her changes back to the central repo,
it is not a fast-forward and is refused.  We currently suggest
Alice to first pull from the central repo (this is how CVS is
used -- you try "cvs commit" and get complaints, then you say
"cvs update" and retry).

What happens is that in Alice's repository, if Bob's change and
Alice's change does not conflict, this "pull" creates a merge
commit.

          .---o---o Alice's 'master'
         /       /
 ---o---o-------o Bob's 'master'
                ^
                central repo's 'master'

Then Alice can push out her changes.

          .---o---o Alice's 'master' == central repo's 'master'
         /       /
 ---o---o-------o Bob's 'master'
                
If Bob pulls from the central repo at this point, it will also
fast-forward and these three repositories end up with


          .---o---o Alice's 'master' == central repo's 'master'
         /       /  == Bob's 'master'
 ---o---o-------o

One thing you _could_ do is to train your users to rebase after
push fails, if you do not want these merges.

After her push fails here...

          .---o Alice's 'master'
         /
 ---o---o-------o Bob's 'master'
                ^
                central repo's 'master'

Alice could rebase by:

	$ git fetch
	$ git rebase origin

The first "git fetch" (if Alice is using the default
configuration created by recent "git clone") fetches from the
central repo and stores the 'master' branch at the central repo
as her tracking branch (.git/refs/remotes/origin/master).  This
can be referenced on the command line as 'origin' (again, if
Alice is using the default configuration created by recent "git
clone").  What these commands do is:

(1) git-fetch makes central repo's 'master' locally available to
    Alice as 'origin'

          .---o Alice's 'master'
         /
 ---o---o-------o Bob's 'master'
                ^
                central repo's 'master' == Alice's 'origin'

(2) git-rebase forward ports the commits on Alice's 'master'
    since it forked from the central repo, and creates this
    graph:


                  .---o Alice's 'master', updated
                 /
 ---o---o-------o Bob's 'master'
                ^
                central repo's 'master' == Alice's 'origin'

After these, 'master' in Alice's repository is a fast-forward
and she can now push to update the central repository.

It would be usually a good idea to rebase if Alice's work is
trivial since she synchronized with the central repository the
last time.  If it is a very involved changes, however, it often
is not worth worrying about keeping merges out of the history.
Your developers _are_ working in parallel and there is not much
point in insisting to lineralize the history too much.