|
|
| Line 1: |
Line 1: |
| = Git commands for a branchy workflow =
| |
|
| |
|
| * TubeTK policy is to follow a [http://nvie.com/posts/a-successful-git-branching-model branchy workflow].
| |
| * All developments should use the branch workflow to maintain an organized git history in TubeTK
| |
| * Key concepts:
| |
| ** Each feature should be developed in its own separate branch on the author's public repository (i.e. the author's clone of TubeTK on Gitorious)
| |
| ** git often uses "topic" as a placeholder for a branch name, because everything in a branch should be on one "topic"--a topic might be to add feature X, refactor subsystem Y, only fix bugs from version Z, and so on.
| |
| ** Once the feature has been programmed and tested, its branch should be merged into TubeTK's master branch ('master' is the git equivalent of cvs 'TRUNK')
| |
| ** After the feature has been merged, its branch should be deleted
| |
|
| |
| TubeTK's central repository is hosted on [www.gitorious.com | Gitorious ]. You can host a public repository to which you "push" and from which others can "pull". If you don't have a server of your own to do this, services like github and gitorious are free for open source projects. After you push to your own public repository, other developers can browse your changes or "pull" them.
| |
|
| |
| == Setting up your personal TubeTK public repository ==
| |
|
| |
| * Create an account at [http://www.gitorious.org Gitorious]
| |
| * Add your computer's public SSH key (log into your gitorious account, go to your "Dashboard" page and select "Manage SSH keys")
| |
| ** Gitorious has an [http://gitorious.org/about/faq FAQ on creating Windows ssh keys]
| |
| * Clone the TubeTK central repository to create your personal TubeTK public repository:
| |
| ** Go to http://www.gitorious.org/tubetk and click the "Clone repository" button
| |
| ** In the examples below, '''<yourName>''' is the name of your Gitorious account
| |
|
| |
| == Setting up your local and remote repositories ==
| |
|
| |
| Your local repository is git's repository local on your machine.
| |
|
| |
| Your remote repositories should be as follows:
| |
| * '''origin''': your public repository
| |
| * '''upstream''': the TubeTK central repository
| |
|
| |
| First, setup your local repository by cloning your public repository. This will create a folder called '''<yourName>'''-tubetk in a directory called 'Projects':
| |
|
| |
| cd Projects
| |
| git clone git@gitorious.org:~'''<yourName>'''/tubetk/'''<yourName>'''-tubetk.git
| |
|
| |
| Optionally, call your local copy '''tubetk''' by adding '''tubetk''' onto the end of the above line.
| |
|
| |
| Then, setup a reference to the TubeTK central repository:
| |
|
| |
| cd '''<yourName>'''-tubetk (or cd tubetk, if you did the optional step above)
| |
| git remote add upstream git@gitorious.org:tubetk/tubetk.git
| |
| git fetch upstream
| |
|
| |
| == Setting up your git environment ==
| |
|
| |
| We have provided a linux shell script for setting up your GIT environment for software development. It is provided in
| |
|
| |
| tubetk/Utilities/SetupForDevelopment.sh
| |
|
| |
| Below are instructions for setting up your environment manually.
| |
|
| |
| If you want a refresher on GIT usage, see [[TubeTK/Development/GITCheatSheet | GIT Tips and Tricks]]
| |
|
| |
| === Setup Global GIT Environment ===
| |
|
| |
| As mentioned above, we have provided a script that will walk you through setting up your GIT environment, below is only necessary if you are setting up your environment manually.
| |
|
| |
| If you are manually configuring your environment, please substitute your information as appropriate into the following commands:
| |
|
| |
| git config --global user.name 'Your Name'
| |
| git config --global user.email 'you@yourdomain.com'
| |
| git config --global color.ui auto
| |
| git config --global merge.tool meld
| |
|
| |
| For more details and other global variable options, see [[TubeTK/Development/GITConfiguration | Manually configuring your global GIT environment]]
| |
|
| |
| === Setup Hooks ===
| |
|
| |
| As mentioned above, we have provided a script that will walk you through setting up your GIT environment, below is only necessary if you are setting up your environment manually.
| |
|
| |
| Hooks check your code prior to allowing it to be committed to the main repository. Details on the checks performed are available at [[TubeTK/Development/GITBranchingUsage/Hooks | TubeTK Hooks]]
| |
|
| |
| The [http://www.kernel.org/pub/software/scm/git/docs/git-commit.html git commit] command creates ''local'' commits. A separate [http://www.kernel.org/pub/software/scm/git/docs/git-push.html git push] step is needed to publish commits to a <code>public.kitware.com</code> repository.
| |
| The <code>public.kitware.com</code> server enforces some rules on the commits it accepts and will reject non-conforming commits. In order to push rejected commits, one must ''edit'' history locally to repair them before publishing. This is a pain and is prone to errors, so we recommend installing '''hooks''' locally to make sure your code is compliant even on local commits.
| |
|
| |
| Enabling TubeTK's local hooks will prevent problems when pushing your contributions to the public TubeTK repository. This is so important to the smooth functioning of git that we REQUIRE that you enable TubeTK's hooks in all clones. TubeTK uses the same hooks as VTK.
| |
|
| |
| Git looks for hooks in the <code>.git/hooks</code> directory within the work tree of a local repository.
| |
|
| |
| cd ~/src/tubetk/.git/hooks
| |
| git init
| |
| git pull git://public.kitware.com/VTK.git hooks
| |
| cd ../..
| |
|
| |
| where <code>''~/src/tubetk''</code> is your TubeTK source directory.
| |
|
| |
| General details on hooks in git are available [http://www.kernel.org/pub/software/scm/git/docs/githooks.html here.]
| |
|
| |
| Optionally, you may now also want to ignore temp files created by your editor
| |
|
| |
| cd ~/src/tubetk/.git/info
| |
| vi exclude
| |
| # now uncomment the "*~" line and, if appropriate, add a "*.swp" line. Then save.
| |
|
| |
| == Adding a feature to TubeTK ==
| |
|
| |
| * A '''feature''' may be new functionality, a new test, a bug fix, performance enhancements, added documentation, style fixes, etc.
| |
| * Each feature should have its own branch
| |
| * Do all of your work in a topic branch, not in master. Do not '''git add'''/'''git update''' in the master branch.
| |
|
| |
| * In the workflow below, '''<topic>''' refers to the name of your branch.
| |
|
| |
| For new features, use the git 'upstream/master' branch as the starting point:
| |
| git checkout master
| |
| git fetch upstream
| |
| git merge upstream/master
| |
| git checkout -b '''<topic>'''
| |
| git push origin '''<topic>'''
| |
|
| |
| All commits for that feature should be committed to the topic branch:
| |
| git checkout '''<topic>'''
| |
| ''' code, code, code '''
| |
| git add -u
| |
| git commit
| |
| ''' code, code, code '''
| |
| git add -u
| |
| git commit
| |
| git push origin '''<topic>'''
| |
| ''' code, code, code '''
| |
| git add -u
| |
| git commit
| |
| ''' code, code, code '''
| |
| git add -u
| |
| git commit
| |
| git push origin '''<topic>'''
| |
|
| |
| After the feature is completed and tested, merge its topic branch to TubeTK's master branch:
| |
|
| |
| Optional: consider rebasing your branch to upstream master. This is optional, but will allow you to address conflicts, verify tests, and maintain a clearer git history. See [http://darwinweb.net/articles/the-case-for-git-rebase "The case for GIT rebase"] and [http://progit.org/book/ch3-6.html "GIT Rebase Documentation"] for more information.
| |
|
| |
| First, make sure that your local master branch is up to date, by fetching and merging all of the changes that have recently occurred on the TubeTK master branch:
| |
|
| |
| git checkout master
| |
| git fetch upstream
| |
| git merge upstream/master
| |
|
| |
| Next, merge your topic branch to your local master branch:
| |
| * The --no-ff option generates a merge commit even if the merge was resolved as a fast-forward merge: using this option makes the history easier to understand
| |
|
| |
| git merge '''<topic>''' --no-ff
| |
| ''' you may have to fix merge conflicts '''
| |
| ''' run tests again, to ensure that the merge did not introduce problems '''
| |
|
| |
| Now, publish your changes to your public repository:
| |
|
| |
| git push origin master
| |
|
| |
| If you're been approved to directly push your changes to the central repository, then after some initial setup of ssh keys its a very simple procedure:
| |
|
| |
| git push upstream master
| |
|
| |
| (If another developer pushed between your pull and your push, you will have to pull and then push again. This isn't expected to happen very frequently, but it will happen more frequently than with cvs since it's required when any file changed, not just when a specific file being committed changed. It is also best to use "git pull --rebase" instead of "git fetch upstream"/"git merge upstream/master" in this case, this will cause the changes from the central repository to be positioned before your own changes, thus skipping a merge.)
| |
|
| |
| Delete your topic branch both locally and on your public repository.
| |
|
| |
| git checkout master
| |
| git branch -d '''<topic>'''
| |
| git push origin :'''<topic>'''
| |
|
| |
| If you want to add more features, start over with a new topic branch.
| |
|
| |
| = Use multiple commits to organize changes =
| |
|
| |
| When appropriate, organize your changes into a series of commits where each commit is a logical step towards your ultimate goal. For example, first factor out some complex code into a new function. Then, in a second commit, fix an underlying bug. Then, in the third commit, add a new feature which is made easier by the refactoring and which would not have worked without fixing that bug.
| |
| This is helpful to reviewers, because it is easier to see that the "factor out code into new function" step was right when there aren't other edits mixed in; it's easier to see that the bug is fixed when the change that fixes it is separate from the new feature; and so on.
| |
|
| |
| = Policy =
| |
|
| |
| Just because a thing can be done with git doesn't mean it should be done.
| |
| * Please don't revise history after it's been made publicly available (i.e. don't revise history after a "git push")
| |
|
| |
| [[Category:TubeTK]]
| |
