GitTutorial

Obtaining PSI4 using Git

As of 11 November 2013, the PSI4 master repository is publicly available on Github:

git clone https://github.com/psi4/psi4public.git psi4

Note: this repository was formerly named psi4release.git. If you cloned that repository, you can convert to the new name by replacing psi4release with psi4public in your psi4/.git/config file.

For those wishing to develop and test new features collaboratively but not publicly, we also have a private repository, ​https://github.com/psi4/psi4.git. Note, however, that changes to the master branch on the private psi4 repository are regularly synchronized with the public master branch, so changes not yet ready for public consumption should be made on private branches. See the core development team for access to the private psi4 repository.

Git tutorial

Now we'll do a quick demo of Git. We want to add something new, so the first step is to create a branch. Branches are very easy in Git, and should always be used because they really help with developing multiple ideas simultaneously. Head into the psi4 directory and create a branch:

git branch great_idea
git checkout great_idea

You can check which branch you are on:

git branch

which will list all known branches, denoting the active one with an asterisk. Now modify an existing file, or add a new one. We can see that there are uncommitted changes by running

git status

which will reveal that there are changes that have not yet been placed under Git's control or committed. To see exactly what these changes are, run

git diff

Now we want to tell Git to track our changes, so we can run

git add [list of files]

where the list of files is the list of all modified files that we want to track changes to, or new files that we want to track. To track all files in the current directory and all subdirectories, you can run

git add .

Any files or folders we never want to track, such as compilation directories, can be added to the list in the .gitignore file in the top directory. Now we've told Git what to track, we can commit

git commit

Which will bring up a vi window, for commit message input. This will commit the changes only to the local repository, and only on the current branch. This means that you should go through the add/commit process as often as possible, to give you a full history of development progress, with the option to revert any of the individual commits. If you're certain you're ready to make your changes available to everyone with access to the PSI4 branches, you can push them to the remote repository on github.com:

git push

If you want to switch back to the master branch, just run

git checkout master

Merging in Git is generally straightforward. For example, if you wish to merge in changes from your branch to master,

git checkout master
git merge great_idea

If there are conflicts, you must resolve them before you can commit and push. Once you've done this, be sure to test the code against the complete test suite before you push your changes to the main repository on github. If the old branch is no longer needed, we can simply delete it

git branch -d great_idea

or we can just check it out again and keep developing. Because making and navigating branches is so easy with Git, they should be used for every new feature.

Git Pull

Pulling new changes from the repository

The git pull command actually performs two operations for you. First, a git fetch command is executed to download new change sets from the repository onto your local system. Second, a git merge is performed bringing the new change sets into your current local branch. If you are not careful, it is this second step that cause headaches.

The first thing you should do is check which branch you are on with git status:

% git status
# On branch master
nothing to commit (working directory clean)
This tells me I'm on the master branch and I haven't edited any files.

Next, tell git to fetch any new change sets and merge them into the current branch:

% git pull origin master
From sirius.chem.vt.edu:psi4
 * branch            master     -> FETCH_HEAD
Already up-to-date.

In this example, my local source and sirius are at the same revision.

Occasionally, the pull will fail because you have locally changed files that would be overwritten. Sometimes, you don't want to lose the changes, and you need to do a git checkin before doing the git pull. Other times, you do want to lose the changes (this can especially happen because of automated changes to the samples directory that will sort themselves out anyway because those directories are mostly auto-generated). In that case, you can just delete the files that are blocking the git pull, and the git pull will restore them with the most recent copies from the repository.

Similarly, the git pull may conflict with a locally committed change. In that case, you need to resolve the conflict. Often, this is as simple as pulling up the file in an editor, resolving some obvious problems (and remembering to remove the conflict markers), and then doing git add [filename] to mark the conflict as resolved (followed by another git commit to check in the resolution). For more complicated cases, git mergetool is recommended. Sometimes, it's clear that you really just want to keep your version, or else just the remote repository's version. That's easy as long as you have git version 1.6.1 or newer, you can just re-check out the file with git checkout --theirs [filename] to keep the remote repository version, or git checkout --ours [filename] to keep your version. Again, once it's all good, you'll need to do git add [filename] and git commit. More information about resolving conflicts is available in our git tutorial.

After you've pulled changes, it's a good idea to ensure that your object directory is fully updated with any new subdirectories, Makefiles, etc. Use the following procedure to get your object directory fully updated.

% cd psi4
% autoconf
% cd objdir [or whatever your object directory is named]
% ./config.status --recheck
% ./config.status
% make

Occasionally, even this "safe" procedure can still lead to problems like getting stuck in an infinite loop while making (if this happens, you'll see make called with increasingly large numbers after the make command, like make[ 75 ]). In that case, delete your object directory entirely and make a new one and recompile according to the installation instructions (making sure you ran autoconf in the top-level psi4 directory before configuring in the object directory).

Git Push

Pushing changes to the repository

Make sure you are on your master branch!

So your master branch is in a state that you feel is ready to commit to the main repository. All you have to do is:

% git push origin master

This tells git to upload your changes to origin (where your clone originated from) to its master branch.

todo: place example screen output from successful git push.

If you see this when you push

% git push origin master
To git@sirius.chem.vt.edu:psi4.git
 ! [rejected]        master -> master (non-fast-forward)
error: failed to push some refs to 'git@sirius.chem.vt.edu:psi4.git'
To prevent you from losing history, non-fast-forward updates were rejected
Merge the remote changes (e.g. 'git pull') before pushing again.  See the
'Note about fast-forwards' section of 'git push --help' for details.

it means that sirius has commits that you do not. Run git pull origin master to obtain them. Resolve any conflicts and compile the code to ensure no new bugs were introduced. Once completed, try your git push again.