issue 142 git subrepo use cases workflows

This page contains some use cases for the issue/142 branch.

State diagram: https://docs.google.com/drawings/d/1gMjINgIEw0lPAAHKPhKMNVjLI2PE9RORGV3BGOTEUHo/edit?usp=sharing

Notation

subrepo: sub
fetched subrepo: fet
parent: par
uppercase letters, commits
uppercase letters with ', transformed commits
triplets, BCA, B is the parent commit, C is the .gitrepo.commit, A is the .gitrepo.parent
v - upstream HEAD
^ - subrepo/branch

Start

sub: A
fet:
par: B

Cloned (will be used as base for the cases below)

sub: A
fet: A
par: B -CAB

Remote work

sub: A - D - E

Pull - step 1 fetch

             v
fet: A - D - E

Description of branch. Take all parent commits from .gitrepo.parent..HEAD and attach them into the fetched data. For each commit check the content of the .gitrepo.commit, if that changes add the new value as parent. In the current state we have

par: B -CAB

So we take B..HEAD in this case C, look at the .gitrepo.commit and sees a new value A instead of nothing, so we transform C into C' and attach it with A as parent.

Pull - step 2.1 branch

             v
fet: A - D - E
       \
         C'
         ^

Pull - step 2.2 --prune-empty should detect C'=A

             v
fet: A - D - E
     ^

Pull - step 2.3 merge, becomes fast-forward

             v
fet: A - D - E
             ^

Pull - step 3 commit into parent repo, update .gitrepo commit and parent

par: A -CAB-FEC

Cloned

sub: A
fet: A
par: B -CAB

Local change

par: B -CAB-DAB-EAB

Push - step 1 fetch

     v
fet: A

Push - step 2.1 branch

     v
fet: A
       \
         C'- D'- E'
                 ^

Push - step 2.2 --prune-empty detects A=C'

     v
fet: A
       \
         D'- E'
             ^

Push - step 2.2 merge (fastforward)

fet: A
       \     v
         D'- E'
             ^

Push - step 3 push into remote, update .gitrepo commit and parent

sub: A - D'- E'
par: B -CAB-DAB-EAB-FE'E

Clone

sub: A
fet: A
par: B -CAB

Conflicting work

sub: A - D - E
fet: A
par: B -CAB-FAB-GAB

Pull - Step 1 fetch

fet: A - D - E

Pull - step 2.1 branch

             v
fet: A - D - E
       \
         C'- F'- G'
                 ^

Pull - Step 2.2 prune-empty (C'=A)

             v
fet: A - D - E
       \
         F'- G'
             ^

Pull - Step 2.3 merge

                 v
fet: A - D - E  
       \       \
         F'- G'- H'
                 ^

Pull - Step 3 commit into parent, .gitrepo commit is updated, parent is NOT

par: B -CAB-FAB-GAB-HEB

If we should push this now We would get this tree in step 2.2:

             v
fet: A - D - E  
       \       \
         F'- G'- H'
                 ^

No merge is necessary as the H' already is a Merge commit, so we can push "as is", when we push we get a new commit on parent

fet: A - D - E - H'
       \       /
         F'- G'
par: B -CAB-FAB-GAB-HEB-IH'H

If we go back and try the rebase version here:

Pull - Step 2.2 prune-empty (C'=A)

             v
fet: A - D - E
       \
         F'- G'
             ^

Pull - Step 2.3 rebase

             v
fet: A - D - E
               \
                F''-G''
                     ^

Pull - Step 3 commit

par: B -CAB-FAB-GAB-HEB

If we would push that, we end up in

Push - step 2.1 branch

             v
fet: A - D - E
       \
         C'- F'- G'- H'
                     ^

Push - Step 2.2 prune-empty (C'=A, G'=H')

             v
fet: A - D - E
       \
         F'- G'
             ^

Push - Step 2.3 rebase

             v
fet: A - D - E
               \
                F''-G''
                     ^

Push - step 3 - push to subrepo

sub: A - D - E -F''-G''