|
|
| (14 intermediate revisions by 3 users not shown) |
| 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
| |
|
| |
| Then, setup a reference to the TubeTK central repository:
| |
|
| |
| git remote add upstream git@gitorious.org:tubetk/tubetk.git
| |
|
| |
| == Setting up your git environment ==
| |
|
| |
| * Configure your [[TubeTK/Development/GITConfiguration | Git environment]]
| |
|
| |
| * For additional info, see [[TubeTK/Development/GITCheatSheet | GIT Tips and Tricks]]
| |
|
| |
| == Setup 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.
| |
|
| |
| Since it is possible to create many commits locally and push them all at once, we provide local Git ''hooks'' to help developers keep their individual commits clean. Enabling these hooks will prevent problems when pushing your contributions to the public TubeTK repository.
| |
| Git provides no way to enable such hooks by default, giving developers maximum control over their local repositories.
| |
| We REQUIRE enabling our hooks in all clones.
| |
|
| |
| Git looks for hooks in the <code>.git/hooks</code> directory within the work tree of a local repository.
| |
| Create a new ''local'' repository in this directory to manage the hooks and fetch VTK's hooks into that directory.
| |
|
| |
| $ 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.
| |
|
| |
| For details on the VTK hooks used with TubeTK (and how to make your commits comply with their requirements), visit [[TubeTK/Development/GITBranchingUsage/Hooks | TubeTK/VTK Hooks]]
| |
|
| |
| General details on hooks in git are available [http://www.kernel.org/pub/software/scm/git/docs/githooks.html here.]
| |
|
| |
| == Remote repository setup ==
| |
| * '''origin''': keeps a master branch that is only a pointer to the TubeTK master branch, + any of your topic branches
| |
| * '''upstream''': has a master branch
| |
|
| |
| == Adding a feature ==
| |
|
| |
| * 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:
| |
|
| |
| 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")
| |
