Development workflow
You already have your own forked copy of the ipython_ repository, by following :ref:`forking`, :ref:`set-up-fork`, and you have configured git_ by following :ref:`configure-git`.
Workflow summary
- Keep your master branch clean of edits that have not been merged to the main ipython_ development repo. Your master then will follow the main ipython_ repository.
- Start a new feature branch for each set of edits that you do.
- If you can avoid it, try not to merge other branches into your feature branch while you are working.
- Ask for review!
This way of working really helps to keep work well organized, and in keeping history as clear as possible.
See - for example - `linux git workflow`_.
Making a new feature branch
git branch my-new-feature git checkout my-new-feature
Generally, you will want to keep this also on your public github_ fork of ipython_. To do this, you `git push`_ this new branch up to your github_ repo. Generally (if you followed the instructions in these pages, and by default), git will have a link to your github_ repo, called origin. You push up to your own repo on github_ with:
git push origin my-new-feature
From now on git_ will know that my-new-feature is related to the my-new-feature branch in the github_ repo.
The editing workflow
Overview
# hack hack git add my_new_file git commit -am 'NF - some message' git push
In more detail
Make some changes
See which files have changed with git status (see `git status`_). You'll see a listing like this one:
# On branch ny-new-feature # Changed but not updated: # (use "git add <file>..." to update what will be committed) # (use "git checkout -- <file>..." to discard changes in working directory) # # modified: README # # Untracked files: # (use "git add <file>..." to include in what will be committed) # # INSTALL no changes added to commit (use "git add" and/or "git commit -a")
Check what the actual changes are with git diff (`git diff`_).
Add any new files to version control git add new_file_name (see `git add`_).
To commit all modified files into the local copy of your repo,, do git commit -am 'A commit message'. Note the -am options to commit. The m flag just signals that you're going to type a message on the command line. The a flag - you can just take on faith - or see `why the -a flag?`_. See also the `git commit`_ manual page.
To push the changes up to your forked repo on github_, do a git push (see git push).
Asking for code review
Go to your repo URL - e.g. http://github.com/your-user-name/ipython.
Click on the Branch list button:
Click on the Compare button for your feature branch - here my-new-feature:
If asked, select the base and comparison branch names you want to compare. Usually these will be master and my-new-feature (where that is your feature branch name).
At this point you should get a nice summary of the changes. Copy the URL for this, and post it to the `ipython mailing list`_, asking for review. The URL will look something like: http://github.com/your-user-name/ipython/compare/master...my-new-feature. There's an example at http://github.com/matthew-brett/nipy/compare/master...find-install-data See: http://github.com/blog/612-introducing-github-compare-view for more detail.
The generated comparison, is between your feature branch my-new-feature, and the place in master from which you branched my-new-feature. In other words, you can keep updating master without interfering with the output from the comparison. More detail? Note the three dots in the URL above (master...my-new-feature).
Asking for your changes to be merged with the main repo
When you are ready to ask for the merge of your code:
Go to the URL of your forked repo, say http://github.com/your-user-name/ipython.git.
Click on the 'Pull request' button:
Enter a message; we suggest you select only ipython as the recipient. The message will go to the `ipython mailing list`_. Please feel free to add others from the list as you like.
Merging from trunk
This updates your code from the upstream `ipython github`_ repo.
Overview
# go to your master branch git checkout master # pull changes from github git fetch upstream # merge from upstream git merge upstream/master
In detail
We suggest that you do this only for your master branch, and leave your 'feature' branches unmerged, to keep their history as clean as possible. This makes code review easier:
git checkout master
Make sure you have done :ref:`linking-to-upstream`.
Merge the upstream code into your current development by first pulling the upstream repo to a copy on your local machine:
git fetch upstream
then merging into your current branch:
git merge upstream/master
Deleting a branch on github_
git checkout master # delete branch locally git branch -D my-unwanted-branch # delete branch on github git push origin :my-unwanted-branch
(Note the colon : before test-branch. See also: http://github.com/guides/remove-a-remote-branch
Several people sharing a single repository
If you want to work on some stuff with other people, where you are all committing into the same repository, or even the same branch, then just share it via github_.
First fork ipython into your account, as from :ref:`forking`.
Then, go to your forked repository github page, say http://github.com/your-user-name/ipython
Click on the 'Admin' button, and add anyone else to the repo as a collaborator:
Now all those people can do:
git clone git@githhub.com:your-user-name/ipython.git
Remember that links starting with git@ use the ssh protocol and are read-write; links starting with git:// are read-only.
Your collaborators can then commit directly into that repo with the usual:
git commit -am 'ENH - much better code' git push origin master # pushes directly into your repo
Exploring your repository
To see a graphical representation of the repository branches and commits:
gitk --all
To see a linear list of commits for this branch:
git log
You can also look at the `network graph visualizer`_ for your github_ repo.