GitMajorWorkflow: Difference between revisions
No edit summary |
|||
(5 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
'''THIS PAGE IS OBSOLETE''' See [[GitHubWorkflow]] instead. | |||
==Introduction== | ==Introduction== | ||
This workflow should be used for almost all code development. It describes how to create your own branch and commit work to that branch. When the code on the branch is ready to go, | This workflow should be used for almost all code development. It describes how to create your own branch and commit work to that branch. When you believe the code on the branch is ready to go, you can email a "pull request" to the Offline heads, who will merge your branch into the head, when they agree it is ready. | ||
If you are new to git, please read the [[GitIntro|git intro]] and the [[GitMinorWorkflow|minor revision workflow]], which is very useful for concepts. | If you are new to git, please read the [[GitIntro|git intro]] and the [[GitMinorWorkflow|minor revision workflow]], which is very useful for concepts. | ||
Line 13: | Line 14: | ||
# as needed, push this branch to the repo | # as needed, push this branch to the repo | ||
# as needed, merge the master branch into your working branch | # as needed, merge the master branch into your working branch | ||
# when the changes are final, merge your branch into the master branch | # when the changes are final, request to merge your branch into the master branch | ||
This workflow may span weeks, so steps 3 and 4 may need to be done several times. It is fine to save your work this way. It may be needed to tag the branch at various times, to pause for testing, for example, or to pass a given state to another worker. | This workflow may span weeks, so steps 3 and 4 may need to be done several times. It is fine to save your work this way. It may be needed to tag the branch at various times, to pause for testing, for example, or to pass a given state to another worker. | ||
Line 52: | Line 53: | ||
git push | git push | ||
Assuming this is a long-term development project, others may have made commits to the head of the master branch, and now you want to make sure your branch will still work with those changes. The procedure is to merge the head of the | If you are collaborating with others you will want to push your branch back to the repository: | ||
git push -u origin <branchName> | |||
Assuming this is a long-term development project, others may have made commits to the head of the master branch, and now you want to make sure your branch will still work with those changes. You may also want to merge in changes made on other feature branches besides master. The procedure is to merge the head of the other branch into your branch. Note that this applies the other branch's commits to your branch, but it does not rebase. The repository will show the merge, but the history of your commits to your branch is still visible. (In a rebase, the work along the other branch up to the rebase is applied, but the record is dropped so it appears the branch starts at the point of the rebase. See [[GitMinorWorkflow]].) | |||
# make sure you have the latest of the remote repo | # make sure you have the latest of the remote repo | ||
git fetch | git fetch | ||
# update your local master to the remote head | # update your local copy of the other branch (here master) to the remote head | ||
git checkout master | git checkout master | ||
git pull | git pull | ||
# | # switch back to your branch | ||
git checkout <branchName> | git checkout <branchName> | ||
# merge the other branch to your branch | |||
git merge master | git merge master | ||
This procedure syncs your local master from origin/master before merging your local master into your branch. Note the possible difference between master and origin/master. <span style=color:red>can you merge origin/master? will the result look the same?</span> | This procedure syncs your local master from origin/master before merging your local master into your branch. Note the possible difference between master and origin/master. <span style=color:red>can you merge origin/master? will the result look the same?</span> | ||
Line 70: | Line 75: | ||
Naming the tag to push prevents accidentally pushing any other tags, though our default is set so that push only pushes current branch. | Naming the tag to push prevents accidentally pushing any other tags, though our default is set so that push only pushes current branch. | ||
Once all development and validation is complete, the branch needs to be | Once all development and validation is complete, and you have merged the latest head of master into your branch, you can email a pull request to the Offline heads. They will make a judgment on whether the pull can happen immediately or if there needs to be more documentation or testing. | ||
Once there is agreement to proceed with the merge, the heads may do the merge itself, or ask you to do the merge. If you need to the do the merge, | |||
If you were told to do the merge, checkout the master branch, merge your branch into it, then push it back. | |||
git fetch | git fetch | ||
git checkout master | git checkout master | ||
git merge <branchName> | git merge --ff-only <branchName> | ||
git push origin master | git push origin master | ||
The "ff-only" switch will abort the merge if you have not merged the latest of master branch into your branch. | |||
==Naming branches and tags== | ==Naming branches and tags== | ||
Line 90: | Line 97: | ||
If you need to tag the branch to label a particular commit, perhaps for testing, replace the "branch" with the version of the tag. The version will start at zero for each new branch and advance | If you need to tag the branch to label a particular commit, perhaps for testing, replace the "branch" with the version of the tag. The version will start at zero for each new branch and advance | ||
v5_7_9-cosmic_target5-v0 # tag | v5_7_9-cosmic_target5-v0 # tag | ||
[[Category:Computing]] | |||
[[Category:Code]] |
Latest revision as of 19:55, 1 June 2020
THIS PAGE IS OBSOLETE See GitHubWorkflow instead.
Introduction
This workflow should be used for almost all code development. It describes how to create your own branch and commit work to that branch. When you believe the code on the branch is ready to go, you can email a "pull request" to the Offline heads, who will merge your branch into the head, when they agree it is ready.
If you are new to git, please read the git intro and the minor revision workflow, which is very useful for concepts.
Overview
The logical steps are as follows.
- checkout or create a work branch
- make revisions and commit them
- as needed, push this branch to the repo
- as needed, merge the master branch into your working branch
- when the changes are final, request to merge your branch into the master branch
This workflow may span weeks, so steps 3 and 4 may need to be done several times. It is fine to save your work this way. It may be needed to tag the branch at various times, to pause for testing, for example, or to pass a given state to another worker.
We have agreed that branches can be temporary or may be very long-lived. In the case of temporary, the branch name would correspond to a specific project. Once the project is finished and the work incorporated back into the main branch, then the branch is left alone at the merge point. In the long-lived case, there may be a more generic branch, such as "geometryDev", which is merged into and out of the main branch for many projects over years.
Cheat Sheet
Begin with a clone
git clone ssh://p-mu2eofflinesoftwaremu2eoffline@cdcvs.fnal.gov/cvs/projects/mu2eofflinesoftwaremu2eoffline/Offline.git
If the branch you want to work on already exists
# make sure you have the current branch commits git fetch git checkout -b <branchName>
or if you are creating it from the head:
# make sure you have the current head git fetch git checkout -b <branchName>
or if you are creating it, and want to start the branch at commit <tagOrCommit>:
git checkout -b <branchName> <tagOrCommit>
If you get a "detached HEAD" warning here, you have done something wrong - do not continue or your commits may get lost.
Make your revisions and commit them. It is important to stay on this branch while committing.
git status On branch branchName
Typically, you will be the only person working on the branch, but if the branch already exists in the repository, here is how to check if there were any other commits to this branch.
git fetch git diff <branchName> origin/<branchName>
If there were commits, you can merge them into your branch
git checkout <branchName> git pull
To push your current branch:
git push
If you are collaborating with others you will want to push your branch back to the repository:
git push -u origin <branchName>
Assuming this is a long-term development project, others may have made commits to the head of the master branch, and now you want to make sure your branch will still work with those changes. You may also want to merge in changes made on other feature branches besides master. The procedure is to merge the head of the other branch into your branch. Note that this applies the other branch's commits to your branch, but it does not rebase. The repository will show the merge, but the history of your commits to your branch is still visible. (In a rebase, the work along the other branch up to the rebase is applied, but the record is dropped so it appears the branch starts at the point of the rebase. See GitMinorWorkflow.)
# make sure you have the latest of the remote repo git fetch # update your local copy of the other branch (here master) to the remote head git checkout master git pull # switch back to your branch git checkout <branchName> # merge the other branch to your branch git merge master
This procedure syncs your local master from origin/master before merging your local master into your branch. Note the possible difference between master and origin/master. can you merge origin/master? will the result look the same?
Conflicts may need to be fixed.
If you need to tag the branch, create tag name and while the branch is checked out,
git tag -a -m "comment" <tagName> git push origin <tagName>
Naming the tag to push prevents accidentally pushing any other tags, though our default is set so that push only pushes current branch.
Once all development and validation is complete, and you have merged the latest head of master into your branch, you can email a pull request to the Offline heads. They will make a judgment on whether the pull can happen immediately or if there needs to be more documentation or testing.
Once there is agreement to proceed with the merge, the heads may do the merge itself, or ask you to do the merge. If you need to the do the merge,
If you were told to do the merge, checkout the master branch, merge your branch into it, then push it back.
git fetch git checkout master git merge --ff-only <branchName> git push origin master
The "ff-only" switch will abort the merge if you have not merged the latest of master branch into your branch.
Naming branches and tags
We suggest branch names made up of 3 parts
- the starting point. Thsi is relevant if the starting point is a tagged release or other significant commit. If the start of the branch is the current head, and has no significance, it can be left off.
- the nemonic name. The string which tells any casual viewer the purpose of the work
- the word "branch"
A branch name might look like:
v5_7_9-cosmic_target5-branch # branch
If you need to tag the branch to label a particular commit, perhaps for testing, replace the "branch" with the version of the tag. The version will start at zero for each new branch and advance
v5_7_9-cosmic_target5-v0 # tag