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
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.
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:
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
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
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
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:
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.