wiki:GitObtaining
Last modified 10 months ago Last modified on 02/23/14 13:48:37

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.

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.