This is a quick refresher of useful git commands and practices for users of direct clones of our central [email protected] repository. This page is geared to people who don’t really use GUNNS directly, but just need to keep it up-to-date inside of a larger project. Git is very powerful and complicated, so we’re just sticking to the bare minimum you need to get by.

All of the command-line statements given below should be run from the gunns/ folder.

See here for initially setting up a new clone in your working area.

• origin: this is what git calls the central repository that you cloned from, i.e. [email protected]:gunns/gunns.git
• remotes: git allows you to sync up your repo with other user’s repos, and not just origin. You can set up a remote to another user and pull from their repo, for example. origin is just another remote — it’s the name of the central repository remote. You always have origin set up as a remote by default.
• branches: it’s important to distinguish between your own local branches in your clone verses branches of a remote, such as origin. We call these “local” vs. “remote” branches.
• A submodule is a git repo embedded inside another repo. gunnshow and ms-utils are submodules inside gunns.

By default, when you initialize your new repo, you will be on your local master branch which is sitting at remote origin/master branch of the central repo.

Depending on which project you are working on, you may want to follow a different branch of origin (see the list of origin branches below). We recommend these steps — we’ll use origin/nexsys as the example branch we want to follow:

1. Create a new local branch and configure it to follow the desired remote branch. You can call it whatever you want, but we recommend something similar to the remote branch you are following. We’ll pick nexsys for our local branch and configure it to follow the remote origin/nexsys in this example:
   

   
   
    $ git branch —set-upstream nexsys origin/nexsys
   
   

2. Now checkout to the new local branch:
   

   
   
    $ git checkout nexsys
   
   

Alternatively, you can also accomplish both of the above steps with one awesome command (thanks Thomas!):

 $ git checkout origin/nexsys -b nexsys

• origin/master: this branch always sits at the last official GUNNS release tag, and we only ever update this branch for a new release. This is the default branch you start at when you create a new clone of the repo. This is the most stable branch and the only one that is supposed to be in a working state at all times, but it lags behind the bleeding edge of development.
• origin/next: this is the GunnSmiths team’s working branch for updates targeted for the next official release. It is usually in a working state, and has Continuous Integration tests performed on it for each update. It is the equivalent of the trunk branch of an svn repo.
• origin/next-nexsys: this branch contains new development for the NExSyS project. GUNNS users in the NExSyS project should use this branch.
• origin/next-hestia: this branch contains new development for the HESTIA project. GUNNS users in the HESTIA project should use this branch.
• origin/next-ts21" this branch contains new development for TS21. TS21 users should use this branch.
• origin/next-boeing: this branch contains new development for project support to Boeing.

Sometimes there might have been updates to the remote repo that you’ll want to pull into your clone in order to stay synced up with project development. To see if there have been updates, do:

$ git status

If there have been updates to the remote that you don’t have yet, the git status command will display a result something like this:

	
On branch nexsys
	
Your branch is behind ‘origin/nexsys’ by 2 commits, and can be fast-forwarded.

#

nothing to commit (working directory clean)

To pull in those updates into your repo, do:

$ git pull

The results will indicate that some files have been updated in your repo. Then if you do a git status again and you’re up-to-date, you’ll see:

# On branch nexsys
nothing to commit (working directory clean)

Whenever you do a pull to update gunns, git may indicate that one of its submodules needs to be updated too. It will say something like this:

WARNING: submodule(s) gunnshow  now out of sync.
You probably want to run:
    git submodule update gunnshow 
in the top level of the repository.

Git doesn’t update submodules for you automatically, so you have to update them yourself. Conveniently, the above message tells you what command to do:

$ git submodule update gunnshow

Or as a shortcut you can just do this to update all submodules:

$ git submodule update

The ms-utils submodule should always be kept up-to-date. You only need to keep the gunnshow submodule up-to-date if you are using the GunnShow tool.