Git/Workflow/Stage
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. | ||
...o----o master,
^ *topic-name
| ||
...o----o master
\
o----o *topic-name
| ||
|
When the topic is ready for publication push it to the stage.
Pushing | ||
|
...o----o master, stage/master
\
o----o *topic-name, stage/topic-name
| |
Viewing all Topics
| Actions | Results | Troubleshooting | |
|---|---|---|---|
|
Print the current stage topic table: | |||
|
...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:
| |||
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. | ||
| ||
|
Print the new state of the stage: | ||
|
...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: | ||
|
...o----o master
\
o----o----o *topic-name
^ stage/topic-name
| |
|
Push the topic to the stage. | ||
|
...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: | ||
|
...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: | ||
| ||
|
Now next can see the whole topic again: | ||
|
...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: | ||
| ||
|
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: | ||
|
...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. | ||
|
...o----o master
\
o----o----o----o *topic-name
^ stage/topic-name
| |
|
Push the topic to the stage. | ||
|
...o----o master
\
o----o----o----o *topic-name, stage/topic-name
| |
|
Merge the topic into next again: | ||
| ||
|
Now next can see the whole topic but none of its changes: | ||
|
...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: | ||
| ||
|
The stage no longer references the topic explicitly: | ||
|
...o----o stage/master
. \ \
. \ o----o----o----o
. \ \ \ \
. o----o \ \ \ stage/other-topic
. \ \ \ \
........o----o----o----o stage/next
| |
