One can check out the golden version of the code with the command,

git clone ssh://orda@botwin.pas.rochester.edu/astrobear

This puts a local copy of the last release of the code (called the 'Master' branch) in your current working directory, in a folder named astrobear. Switching into the folder astrobear, you can see the branch's name with the command,

git branch

which shows you the current branch you are on (marked by an '*') out of the list of local branches you have checked out. If you just cloned the repo, the only branch in this list is the master. But you can see all the branches of the larger repo of the code, by giving the command,

git branch -a

Now, to do development, one switches to the development branch of the code, which is the 'living' part of the code (i.e. that which is being developed, tested, and updated) that exists between golden releases of the code.

You switch to different branches (to the development branch in this example) with the command,

git checkout development

Giving

git branch

Now shows you have 2 local checked out versions of the code, master and development, and that you are currently sitting in the development branch (marked by an '*').

From there, if you want to begin making changes to the code, you must create a new branch off of the development branch, for which you will later merge (see below) with the development branch after your edits have been tested.

git checkout -b your_new_branch

This will take the current version of the development code and create an offshoot of it (i.e. a copy of it) for you to then work with.

This new branch is only a local copy, meaning that if you were to delete your directory, your branch (and all of its changes) would cease to exist (i.e. no copy of it is yet present in the central repo), and that no one else can see it. So, in order to sync your local copy with the main repo, you want to push (i.e. copy) this branch into the central repo,

git push -u origin your_new_branch

Now others would see your branch if they downloaded a clean version of the repo, or updated theirs with,

git pull
git branch -a

After that initial push, one only needs to do a simple

git push

to update the central repo with new edits. Before that however, one should "add" and "commit" changes to their local copies, or else nothing new will be available to be pushed.

Now, what does "add" mean anyway — it means "staging" changes to be committed, i.e., making them available to be committed. After one has edited some files in their branch, they can give the command,

git status

This shows ALL of the uncommitted edits of your branch. It reports a ton of uninteresting files after you compile — object (.o) files and the like that are never going to be committed to the central repo and are therefore named 'untracked' files. To get rid of these uninteresting files, use the option -uno,

git status -uno

This will now report a list of changes you made since the last commit. If you want to diff the version of any of these files with previous commit's versions, you would use the command

git diff filename HEAD~1 --stats

The head~1 is the last committed branch, ~2 is the 2nd to last, etc. Without specifying the pointer (i.e. HEAD), one diffs the uncommitted file with the last committed version by default. Note, that once you commit, you can no longer diff the files by default, and need to specify the pointer.

Another way you might go about looking at old files, is to use the command

git show commit#(or HEAD~1, etc.):filename > "old.f90"

and do a regular diff from the terminal, e.g.:

diff old.f90 new.f90

The commit # is found in

git log

Now, the procedure for pushing changes into the development branch goes as follows. Once your changes are ready to go into the dev branch, you want to switch back to the development branch and update it so that your changes are going to be merged with the newest version of the dev branch. You do this with,

git checkout development
git pull

Once you have done this, you want to switch back to your working branch so that you can merge the development branch into your working branch, rather than the other way around:

git checkout your_branch
git merge development

The differences in the 2 situations is illustrated below:

The 'good' option shows your changes going 'ahead' of the development branch, i.e. your branch contains the new additions to the development branch. The 'not-good' option, which would be you merging your branch into the development branch shows that this would update the development branch to have all of your changes. Ideally, this is left to the main developers of the code (i.e. Jonathan and Baowei), and only happens after thorough testing of any new/modified code.

Once you have merged, you then want to push those changes back into the repo.,

git push

Once you are done with your edits, you can delete your local copies of the repo with,

git branch -d your_branch

However, deleting your repo from the central repo is not possible on your own, and you need to ask Jonathan or Baowei to do this for you (i.e. pruning branches should be done with caution).

As a tip, you can always use the command,

git help command_name

Also as a misc. command, when you are moving files, you should use the command

git mv file

to track the move.

And lastly, note that one can not simply pull changes from different branches of the code; they are separate entities, unless connected by a branch. If you want changes from another person's development branch, you need to merge. Just think about which direction would be best.