Setting up to modify Antelope contrib via git

If you wish to submit modifications to the Antelope contributed code-base, there are numerous ways to accomplish the task. Also, as a community our model for git repository management is still evolving. Further understanding is available from the numerous books and tutorials available about git. This page presents one currently recommended path, which may evolve with time.

1. Make sure you have the Git source-code management tools properly installed and ready to use on your system. (Try typing git on the command-line of your terminal. If it emits a usage line, you’re probably ready to move to the next step.) If not, refer to http://www.git-scm.com (or http://git.or.cz) to download and install git.

2. Make a github account for yourself if you don’t already have one. In the following example, we’ll assume you’re making an account under the name janedoe. Sign in to this github account on github.

3. Navigate to the Antelope contributed-code git repository at http://github.com/antelopeusersgroup/antelope_contrib. Near the upper right-hand corner of the page, hit the Fork button to create your own copy of the contributed-code repository. You will now have your very own public repository for Antelope contributed-code, stored under

http://github.com/janedoe/antelope_contrib

At this point it may be valuable to peruse the extensive help available at The github help page.

4. There are now conceivably several ways to proceed. For the sake of directness, this outline will explain one. First set up your ssh key with github so you can download your repository via your personal URL, which allows you to submit changes to your personal copy of the repository (unlike the public URL for your repository, which provides read-only access for the public). After adding your ssh key to your github account:

% cd $ANTELOPE
% mkdir src
% cd src
% git clone [email protected]:janedoe/antelope_contrib.git contrib
% cd contrib

If all goes well, this should create a copy of the antelope contributed-code repository on your local machine.

At this point, it’s nice to configure the repository so it knows your correct name and email address, which will show up in commit messages. Make sure you’re in the $ANTELOPE/src/contrib directory or a subdirectory when you execute this and all other git commands relevant to this repository (otherwise git won’t be able to find it’s notes on this repository):

% git config --global user.name "Jane Doe"
% git config --global user.email "[email protected]"

5. If you’re feeling adventurous, add the main Antelope Users Group repository as another remote repository (this will be quite useful later on, to compare the main repository with what you’ve done in your own):

% git remote add gh_aug git://github.com/antelopeusersgroup/antelope_contrib.git

The string gh_aug is a nickname for the main remote repository, chosen to mean “github—antelope users group”. In practice, you can use any nickname you wish.

6. You can now work in your repository, adding features and/or experimenting with code ideas as you wish. Again, numerous workflows are possible — this document will sketch only one. One note: it is strongly advisable to cordon off each set of related changes into its own git branch. Creating different branches is very inexpensive in git. If you do not get in the habit of using lots of branches for each of your separate endeavors, submitting your changes back to the central repository will create numerous difficulties for yourself, if not also for other parties involved.

Let’s add a program to the Antelope contributed-code repository, submit it back to our personal github fork of antelope_contrib, then issue a Pull Request to have our changes included in the main repository. The following example presumes you’re already in the $ANTELOPE/src/contrib directory:

% git checkout -b dev/dbsome_utility origin/master
% cd bin/db
% mkdir dbsome_utility
% cd dbsome_utility
% vi dbsome_utility.c
% vi dbsome_utility.1
% vi Makefile
% git add dbsome_utility.c dbsome_utility.1 Makefile
% git commit -m 'New database utility to do X'

This example creates the new program dbsome_utility in a new git branch called dev/dbsome_utility. Note that upon executing the git-commit command, a short message is included indicating the general nature of the change. Please make a practice of writing short, informative commit messages for the health of the repository and the sanity of your colleagues. Thanks!

Now if tests succeed for the new program, we can merge it into our master branch. Note that before doing so it’s nice to update our master branch (via the git pull command in the example below) to be concurrent with the main Antelope Users Group code base:

% git checkout master
% git pull gh_aug/master
% git merge dev/dbsome_utility
% git push

If all goes well, the new program dbsome_utility will be part of your personal github copy of antelope_contrib, immediately available for public use. If you’d like, you can notify colleagues of this right away and they can begin experimenting with it, directly out of your own fork of antelope_contrib. (If you want to be really fancy, you can push the new utility to a non-master branch of your own repository, continuing to develop it there in collaboration with colleagues until all the bugs are worked out).

As an alternative example, if you just want to modify an existing file in the repository, do something like the following:

% git checkout -b dev/fix_existing_utility origin/master
% cd bin/db/existing_utility
% vi existing_utility.c
% git add existing_utility.c
% git commit -m 'Add feature X to existing_utility'

Unlike other revision control systems such as CVS, with git there are actually two steps to get your changes committed, first git add and then git commit. The git add command is necessary to put your changes into the temporary index git uses to stage changes about to be made. The following git commit command then inserts those changes into your branch when you are ready. Once your changes are committed, you can merge them into your master branch:

% git checkout master
% git pull gh_aug/master
% git merge dev/fix_existing_utility
% git push

7. Once you’re ready for the module to be incorporated into the main Antelope Users Group repository, navigate to your own github account page for antelope_contrib, e.g.

http://github.com/janedoe/antelope_contrib.git

and hit the Pull Request button near the upper right. This requests that one of the collaborators on the Antelope Users Group page pull in the changes from your fork of the repository into the main repository. (Note here the distributed, non-central nature of git: there’s nothing to prevent the janedoe repository from becoming more authoritative than the antelopeusersgroup repository, other than community convention. Also note that as the transition of Antelope-contrib to git evolves, we will endeavor to eliminate the middle-people in the collaboration model.)

(As a final note, make sure not to make any manual changes to the epicenter/epicenter_cvs branches. These are the mirrors of the CVS Antelope-contrib repository, which are automatically merged into the github master branch. Any manual changes will probably hamstring the automation. Also, in the name of protecting the automation for as long as possible, once you start modifying an antelope-contrib program via git, it is best not to submit any more changes for that program via CVS, or a large mess may result, necessitating the immediate abandonment of the CVS repository, rather than gradual phase-out).