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.
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. | ||
| ||
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 |