I am writing this post with the intention of giving readers (and other sysadmins) that are unfamiliar with Git a brief introduction to get up and running as quickly as possible.  There are numerous guides out there but none I have found so far with the spin of getting things working quickly for system administrators.  I recently went through the process of submitting some work of mine to an Open Source project and went through all of the work myself and thought I would write up a little guide to getting started, just in case anyone is interested.  Because of this experience, I thought the process could be streamlined if I presented a simple set of steps and examples for other sysadmins so that they can get started and get comfortable using Git as quickly as possible.  By no means am I advocating that I am a Git expert, I simply know enough to “do stuff” so take this guide for what it is, a simple introduction.  Hopefully it is enough to get the ball rolling and get you hooked on revision control!

Step 1:  If you haven’t already, head over to github and set yourself up with a free account.  The steps are trivial, just like setting up any other account.  You will need to install Git on you machine locally so that you can do everything, sudo apt-get install git in Ubuntu, or, with a little more legwork if you are using Windows.

Step 2:  Once you are all set up and running you can either create a new repository or fork off of somebody else’s repo, which will essentially make a copy of their work to your user account in github.  Since I was contributing to a public project I forked their repo.  This is typically (for beginners at least) done through the website by browsing to the project you are interested in and then clicking the fork button at the top right.

Once you have copied or forked the project you want, you can begin working on making your own changes and updates to the project.  This is where much of the initial confusion came in for me.  I should make a note here; there are a few things that must be done through the website and others that should be done with the git tool you downloaded and installed earlier.

Step 3:  Clone the repo down to your machine locally to begin making changes.  This is done via command line with the following:

git clone https://github.com/$username/repository.git
git clone https://github.com/jmreicha/curriculum.git

Once you have the repo cloned down to your machine, let’s create a branch which we will use to work on the specific piece of the project we are working on.  There are a few more common commands that are used for working with repos.  In some scenarios the public project may change or get updated while you are working on it so you might want to pull in the most recent changes to your own fork.  The following commands are used to work with public repos and forks.

Fetch new changes from original repo:

git fetch upstream

Merge the fetched changes into your working files:

git merge upstream/master

Pull newest updates and changes from a for or repo:

git pull

Okay, let’s assume that our repository is all up to date and we are ready to start working on the new changes that we want to make.  First, we need to create a local branch to make the changes on.  The command for creating a branch is:

git checkout -b $topic
git checkout -b my_topic

Where $topic is the specific change you will be working on.  Then go ahead and make your changes and/or updates with your favorite text editor.  If you have multiple changes to make it may be a good idea to create a few different branches using the command above.  To switch between branches use the following:

git checkout $branchname
git checkout my_topic

If you are working on a branch and either don’t want to commit the changes or the branch becomes obsolete, you can delete the branch with either of the following commands:

git reset --hard
git branch -d $branchname
git branch -d my_topic

Step 4:  Assuming you are all done with your branches and are finished making your changes the next step is to commit the changes.  This will basically record a snapshot of (the state) the files.  Typically for a commit you will want to do one thing at a time to keep track of things more easily.  So you will make one change and then commit and then repeat if there are numerous changes that need to be made.  The command is:

git commit -am "update goes in here"

Now that we have created a branch, made our changes, written our changes so that git knows about them and can keep track of them, we are ready to go ahead and merge the code that we have changed locally back up to github.  Start by pushing the branch up to the github repo.

git push $remote $branchname
git push origin my_topic

Next, merge your changes.  This is done by changing to the “master” branch and then issuing a merge command on the branch that was created to make changes into.  So here is what this process would look like:

git checkout master
git merge $branchname
git merge my_topic

alternatively if you just want to quickly push out a change to the master branch you can issue a git commit locally and then a git push to update the master branch without merging the items first.

git commit -am "updated message"
git push

I like to use this for local repositories where I just need to get things up quickly.

Step 5:  At this point everything should be accurate on your own personal github page.  You can double check your commit history or look at the last update time to make sure your changes worked their way into your public fork or repo.  If you are contributing to a public project the final step is to issue a pull request on the github site.  Once this is done, wait to hear back from a moderator of the project if your changes need to be fixed before they accept them or wait for a response saying that your changes were good and get merged to the project.

Git, to me, was a little bit confusing at first.  Like I said earlier, I still only have a generic and basic understanding but I think it is important for system administrators to know how to commit code to projects and how to keep track of their own code and projects as well.  Even if the code is only small scripting projects it is still beneficial to publish since github is a public site.  Potential colleagues and employers can browse through your work, which increases your visibility and can even lead to job offers.

If you’re interested in learning more, I found this site to be a great resource.