GitAipy

From AstroBaki
Jump to navigationJump to search

How to Use GIT with AIPY[edit]

We've adopted GIT as a revisioning system on the AIPY source. GIT fills the same role as CVS or SVN, but seems to be less clunky, and more flexible about branching and merging. The idea is that anyone who wants to develop can pull a fully-functional repository from any other developer, branch it, make edits, and merge their branch back with anyone else's. The central AIPY repository is hosted at http://github.com/AaronParsons/aipy, and releases will be made from this repository to the AIPY download page at http://pypi.python.org/pypi/aipy.

I am optimistic that this revisioning style will help people pursue their own personal interests, while allowing useful features to be adopted into AIPY's core with minimal complications.

For an overview of common GIT commands, see this cheat sheet and this guide. You can also get help on any GIT command by typing:

git help {command}

Setting up GIT[edit]

Getting GIT should probably be just like getting any other software package (i.e. you should be able to use `yum` or `apt-get`). If that doesn't work, try the GIT homepage at http://git.or.cz.

Once you have GIT installed, you should register your information. This is what GIT will use for recording your contributions:

git config --global user.name "Your Name"
git config --global user.email "yourname@somewhere.edu"

That should be enough to make you ready to start a GIT repository.

Getting the AIPY Code[edit]

To get a fully-functional copy of the latest repository (including revision history, branches, etc.) type:

git clone git://github.com/AaronParsons/aipy.git

(This will be a ~10MB download). Once you have a copy of the repository, you can always update it to the latest revision by typing:

git pull {location} {branch}

If you omit `{location}` and `{branch}`, it will pull from `origin` (= http://github.com/AaronParsons/aipy.git) for your currently active branch. You don't always have to pull from the `origin`. You can pull from your friends, too.

To see what you've got, try the following commands:

git log
git tag -l
git status

Editing[edit]

Before you go too crazy customizing AIPY to your project, take a close look at calibration files (which are tied in through AIPY's loc.py module). You should be able to do a lot of customization through this interface without touching the AIPY source. This includes subclassing Antenna, !AntennaArray, Beam, !RadioFixedBody, and !SrcCatalog to implement any specific simulation-related functionality you are shooting for. Most commonly, it will be the scripts (in aipy/scripts) that you'll be wanting to edit.

The first thing you should probably do if you are editing code is branch from the `master`. This will ensure that you have a self-consistent set of code that you can manipulate, save, and exchange with others without interfering with the main development path of AIPY. Don't worry: you can still merge in updates from the master branch, and if you come up with something that should be in the master branch, you can apply the changes in your branch to the master. To make a branch named `mywork` and switch to it, run:

git branch mywork
git checkout mywork

Then you can edit away. If you want to add/remove/rename files or directories, you can help git find them by using `git add`, `git rm` and `git mv`. After making changes, you can see what you've done using:

git diff
git status

After editing, you can commit your changes with:

git commit -a

and then type in a description of your changes. You can also get rid of any changes you made since your last commit by typing:

git reset

If you'd like to tag the status of the code after the commit with special name, you can type:

git tag {tag-name} {key}

where `key` is first few digits of the hex number echoed out after your commit (also accessible through `git log`).

Merging[edit]

If you've got a bugfix or a new feature that you'd like to merge into `master`, you should first make sure that your master branch is up-to-date:

git branch master
git pull

If you want to merge everything you did in `mywork` into `master`, type:

git pull . mywork

Otherwise, if there is a particular commit that contains the edits you'd like to propagate into `master`, type:

git cherry-pick {key/tag-name}

In order to keep things cherry-pickable, you should generally make separate GIT commits for each separate change you make to the AIPY source.

If you ever want to reset back to an earlier commit, you should try:

git reset {key/tag-name}

This will move you back to an earlier commit, but retain any edits you've made to files since the last commit (assuming these are compatible with the commits being undone). If you want to get rid of you edits as well, add `--hard` to the command.

Uploading Changes[edit]

To propagate a change into the central repository, you will need to have the public SSH key for your machine registered with the AIPY project. Contact Aaron Parsons (aparsons at astron berkeley edu) to have this done. After you have your public key registered, you can run:

git push git@github.com:AaronParsons/aipy.git

Alternately, you can share your revisions with someone who already has access to the central repository. Just ask them to pull from you.

To upload a branch to a remote repository tell git to create it with:

git push git@github.com:AaronParsons/aipy.git mybranch:refs/heads/mybranch