Git/Workflow/Stage
 | This page is currently inactive and is retained for historical reference. Either the page is no longer relevant or consensus on its purpose has become unclear. To revive discussion, seek broader input via a forum such as the village pump. |
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.
Fetch from the stage just before pushing to help git compute a minimal set of objects to push.
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. If merging fails with conflicts the stage will print instructions. | ||
| ||
|
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, such as using git revert. | ||
|
...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
| |
