This documentation is for a development version of IPython. There may be significant differences from the latest stable release (1.1.0).
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.
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
# hack hack git add my_new_file git commit -am 'NF - some message' git push
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).
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).
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.
This updates your code from the upstream ipython github repo.
# go to your master branch git checkout master # pull changes from github git fetch upstream # merge from upstream git merge upstream/master
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 Linking your repository to the upstream repo.
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
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
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 Making your own copy (fork) of ipython.
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 email@example.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