Git/Workflow/Stage

From KitwarePublic
Jump to navigationJump to search

Introduction

Our Topic Stage repositories provide a central staging area for topic branches under development. Unlike an official repository a topic stage may have any number of branches. Developers are free to create, update, and delete topics in the stage through Git's ssh protocol.

Tutorial

Initial Setup

Add a remote called "stage" to refer to the topic stage. In general the stage for some upstream repository repo.git is stage/repo.git:

$ git remote add stage git://public.kitware.com/stage/repo.git
$ git config remote.stage.pushurl git@public.kitware.com:stage/repo.git

One may fetch from the stage at any time:

$ git fetch stage --prune

Use the "--prune" option to remove local references to remote topic branches that have been deleted.

Staging a Topic

Actions Results Troubleshooting

Create a local topic branch and develop on it. Here we use the placeholder topic-name for the branch name.

$ Create a Topic
...o----o  master,
        ^ *topic-name
$ Commit Changes
...o----o  master
         \
          o----o *topic-name

When the topic is ready for publication push it to the stage. Pushing HEAD will automatically use the topic-name:

$ git push stage HEAD
To git@public.kitware.com:stage/repo.git
* [new branch]      HEAD -> topic-name
...o----o  master, stage/master
         \
          o----o *topic-name, stage/topic-name

Viewing all Topics

Actions Results Troubleshooting

Print the current stage topic table:

$ ssh git@public.kitware.com stage repo print
         ... | ...
  topic-name | master=0 next=0
 other-topic | master=0 next=1
         ... | ...
...o----o  stage/master
 .  \    \
  .  \    o----o  stage/topic-name
   .  \
    .  o----o  stage/other-topic
     .       \
      ........o  stage/next

Each row represents one topic. The first column names the topic, the rest name each integration branch with a 0 or 1 indicating whether it can reach the topic.

One may also get machine-readable output:

$ ssh git@public.kitware.com stage repo state
branch  9138476e64ec082d7d507c430c7d3fb0d6a6b586 next
branch  b78573d359b74e11f1233a55ee3a0a257973dfa1 master
topic   171b4573096612971f3b8d227a5b372be3281ca4 topic-name
topic   f68c277ddb11780c560d376a864cc5706eb7cc62 other-topic
merged  9138476e64ec082d7d507c430c7d3fb0d6a6b586 f68c277ddb11780c560d376a864cc5706eb7cc62
...

Merging a Topic

Actions Results Troubleshooting

Tell the stage to merge the topic into next. It automatically computes a merge commit based on the latest upstream next.

$ ssh git@public.kitware.com stage repo merge -b next topic-name
Fetching upstream next
Merge branch topic-name
Pushing upstream next
To ../../repo.git

Print the new state of the stage:

$ ssh git@public.kitware.com stage repo print
         ... | ...
  topic-name | master=0 next=1
 other-topic | master=0 next=1
         ... | ...
...o----o  stage/master
 .  \    \
  .  \    o----o  stage/topic-name
   .  \         \
    .  o----o    \  stage/other-topic
     .       \    \
      ........o----o  stage/next

Updating a Topic

Perhaps after merging to next you discover that an additional change is needed.

Actions Results Troubleshooting

Since the merge was done by the topic stage repository we never switched branches locally. Just continue development:

$ edit files
$ git commit
...o----o  master
         \
          o----o----o *topic-name
               ^ stage/topic-name

Push the topic to the stage.

$ git push stage HEAD
To git@public.kitware.com:stage/repo.git
   171b457..27c71e8  HEAD -> topic-name
...o----o  master
         \
          o----o----o *topic-name, stage/topic-name

The stage's reference to the topic will fast-forward. We can see that the topic head is no longer reachable from next:

$ ssh git@public.kitware.com stage repo print
         ... | ...
  topic-name | master=0 next=0
 other-topic | master=0 next=1
         ... | ...
...o----o  stage/master
 .  \    \
  .  \    o----o----o  stage/topic-name
   .  \         \
    .  o----o    \  stage/other-topic
     .       \    \
      ........o----o  stage/next

Merge the topic into next again:

$ ssh git@public.kitware.com stage repo merge -b next topic-name
Fetching upstream next
Merge branch topic-name
Pushing upstream next
To ../../repo.git

Now next can see the whole topic again:

$ ssh git@public.kitware.com stage repo print
         ... | ...
  topic-name | master=0 next=1
 other-topic | master=0 next=1
         ... | ...
...o----o  stage/master
 .  \    \
  .  \    o----o----o  stage/topic-name
   .  \         \    \
    .  o----o    \    \  stage/other-topic
     .       \    \    \
      ........o----o----o  stage/next

Finishing a Topic

After development of the topic has been finished and it is considered stable.

Actions Results Troubleshooting

Merge it to master:

$ ssh git@public.kitware.com stage repo merge -b master topic-name
Fetching upstream master
Merge branch topic-name
Pushing upstream master
To ../../repo.git
Deleting fully merged topic topic-name (27c71e8) from stage.

The "Deleting ..." line occurs when the topic is reachable from all integration branches. Fear not, the deletion is safe even during a race condition when someone else updates it with a new commit at the same time as your merge completes.

The stage no longer references the topic explicitly:

$ ssh git@public.kitware.com stage repo print
         ... | ...
 other-topic | master=0 next=1
         ... | ...
...o----o-------------o  stage/master
 .  \    \           /
  .  \    o----o----o
   .  \         \    \
    .  o----o    \    \  stage/other-topic
     .       \    \    \
      ........o----o----o  stage/next

Abandoning a Topic

Sometimes a topic proves to be unusable and should never be merged to master.

Actions Results Troubleshooting

Add a commit to the topic that reverts all its changes.

$ edit files to revert changes
$ git commit
...o----o  master
         \
          o----o----o----o *topic-name
                    ^ stage/topic-name

Push the topic to the stage.

$ git push stage HEAD
To git@public.kitware.com:stage/repo.git
   27c71e8..7892e6b  HEAD -> topic-name
...o----o  master
         \
          o----o----o----o *topic-name, stage/topic-name

Merge the topic into next again:

$ ssh git@public.kitware.com stage repo merge -b next topic-name
Fetching upstream next
Merge branch topic-name
Pushing upstream next
To ../../repo.git

Now next can see the whole topic but none of its changes:

$ ssh git@public.kitware.com stage repo print
         ... | ...
  topic-name | master=0 next=1
 other-topic | master=0 next=1
         ... | ...
...o----o  stage/master
 .  \    \
  .  \    o----o----o----o  stage/topic-name
   .  \         \    \    \
    .  o----o    \    \    \  stage/other-topic
     .       \    \    \    \
      ........o----o----o----o  stage/next

Finally, push an empty ref to the stage to delete the topic:

$ git push stage :topic-name

The stage no longer references the topic explicitly:

$ ssh git@public.kitware.com stage repo print
         ... | ...
 other-topic | master=0 next=1
         ... | ...
...o----o  stage/master
 .  \    \
  .  \    o----o----o----o
   .  \         \    \    \
    .  o----o    \    \    \  stage/other-topic
     .       \    \    \    \
      ........o----o----o----o  stage/next