Published on 15 September 2014 by

Let’s have a quick review, shall we?

If you have worked through this tutorial series so far, you'll recall that we’re teaching your cat how to use just enough of the open source tools needed to make it through Puppet Fundamentals. We installed the Learning VM (virtual machine) in our intro, learned some important command line commands, and learned how to edit a document in vim. This blog post — the final one in our series — is about how to use Git. Once you finish this tutorial, you'll have all the basic learning you need to start learning Puppet on your own, or by taking one of our training courses. (You'll find all these resources in the Learning section of our site.)

What is GIT?

Git is a version control system (VCS) — a tool to help you keep track of changes. This is great for identifying What Went Wrong™ and figuring out how to fix it.

Git works equally well for teams and individuals. Open source people love it because it is very effective when you have herds of cats making lots of changes to the same stuff. (Also because it was created by Linus Torvalds, who created Linux.) It helps to think of Git as a tracking system that stores every revision of a document.

Open source contributors often use Git with GitHub or Bitbucket. People contributing code to a proprietary system also use Git often within their organization's network. That’s because they expect to have multiple people working with them on a given project, so when you use GitHub (or a system like it), you are sharing your changes in a repository (repo) that other people can have access to.

We’re going to start off by having you use Git by yourself, then work our way up to pulling code from GitHub, and finally to you committing (i.e., contributing) code back to GitHub. To get started, I’m going to use a metaphor to help digest the concept of Git: packing for a series of trips.

You are planning a series of trips, probably to different places, possibly with your cat and other people, and you need to pack your suitcase. You lay out clothing, toiletries and laser pointers on the bed. When you think you’ve found and laid out everything you need, you put it in the suitcase. Since there will be a lot of trips and you will pack your suitcase many times, you will want to leave a note to yourself about what you’ve packed, or whether you have removed anything. You will probably use the same toiletries for each trip, but pack clothes for different climates.

We can think of your suitcase as a git repo. The command git init will start a new repo, or to continue with our travel metaphor, open up a suitcase. The space where you lay out your clothes is your working directory, and when you lay out something that will go in the suitcase, you are staging it. You do this by typing git add t-shirt, or, more likely, git add README.txt.

Putting everything in your suitcase is called a commit, and you move everything from the staging area to the suitcase by typing git commit. This command will take you into vim to make a note about the changes you made in this commit — for example, added flip flops. You must save and quit vim (:wq) after you’ve added that message. Then this version of your magic suitcase is saved in your git logs so you can reference it whenever you need it.

(Pro tip: Typing git commit -m ‘packed bag for the Miami trip’ lets you skip going into vim, and uses what you quote after -m as the commit -message).

Photo of cat in suitcase - cat is committed, while clothes outside suitcase are staged.
Thanks to John Wright for original image on Flickr.

Now before we get started, let’s do a little housekeeping. Type git config --global user.name Duke, replacing “Duke” with your name. Hit enter, then type git config --global user.email [email protected], using your email address in place of Duke’s. This sets your name and email for Git at a global level, meaning in your home directory, so these settings will apply to everything you work with in or below the home directory of your computer. Now you won’t have to type your name and email address ever again. You will want to do this for each computer you use, including the computer that has the Learning VM. Now let’s make our first commit!

Initial Commit

When you type git init, it turns whatever directory you are in into a magical suitcase. Let’s make a new directory just for this exercise. Type cd to get to your home directory, make a new directory called “magic suitcase” by typing mkdir magic_suitcase, and go into it with cd magic_suitcase.

To initiate git, which will track all the things that happen inside this directory, type git init. Now to see what’s going on, type git status.

We are told here that we are on our initial commit (we haven’t packed anything yet), and that there is nothing to commit (we haven’t laid anything out to be packed yet).

So let’s start packing! Type vim lucky_shirt.txt to open the file in vim, go into vim’s insert mode by typing i, and then type The ‘keep calm and git revert’ shirt. Save and quit the file by hitting Escape, then typing :wq. Now, when you type git status, it lets us know that there is an untracked file, lucky_shirt.txt. An untracked change is something we changed, but haven't yet staged. It's like something we have put on the floor or on the bedroom dresser for packing, but haven't yet laid out on the bed to actually pack. Helpfully, the git status command also tells us how to stage the changed file.

Screenshot of git status command 1

The command git add lucky_shirt.txt will stage my lucky shirt so I can commit it later. It’s like I’ve staged it on the bed, so I know with certainty it will be packed into the suitcase, and not forgotten on the nightstand. Now, if we were to type git status, it would show:

Screenshot of git status command 2

Let’s create a few more files and add them…

Screenshot of adding files

Photo of cat in suitcase that's ready to zip closed.
It's getting crowded in here! Thanks to Shannon for the original image on Flickr.

Let’s say that’s enough for our first trip, and go ahead and pack it all. Type git commit. We are taken into vim to make a note about what is being committed. The traditional first message is initial commit, but I added for hiking trip to give myself some clarity. Save and quit vim, and voila! Now you've used git to commit a change! This is the bare bones of using git to collaborate on software or IT projects.

Making Changes

If you decided that you actually own a luckier shirt than the one you packed last time, you could change the lucky_shirt.txt file to say something like “the Kitty Coderz shirt”. If you type git status, you’ll see that now the lucky shirt file is in the changed-but-not-modified section, instead of the added-to-commit section. You still have to type git add lucky_shirt.txt to stage a file that you’ve changed.

If you want to look at specific changes to the file, type git diff and you will see the exact lines where things have changed (git diff --color might make it easier to see). The lines with differences will be between @@ symbols, the committed version will be marked with minus signs, and the changes will be marked with plus signs, just like this:

The git diff command shows exact lines where things have changed.

After adding the new lucky_shirt.txt file, I type git commit -m ‘updated lucky shirt’. (The -m ‘message’ allows me to add the commit message without going into vim.) Yup. It’s that easy!

Let’s say you want to remove the file hiking_boots.txt because you’re going to the beach, not hitting the trails. Typing the command git rm --cached hiking_boots.txt will delete it from the repository (take it out of the suitcase) once you commit, but it will stay in your working directory. If you want to destroy my_sweater.txt from both the repository and the working directory, you would leave out the --cached flag and type git rm sweater.txt to remove my_sweater.txt everywhere, forever.

The shorthand notes section:

  • git init — this command is only for when you start
  • git add <filename> — for adding new or modified files or directories
  • git status — makes sure we’ve got everything staged that we want to pack
  • git diff — for when we want to see the exact changes
  • git commit — we start to zip up the suitcase
  • i <insert commit message here> esc :wq — command for leaving a note about what’s inside the suitcase (what’s been changed)

Git Log

Sometimes you need to look at things you packed in the past. When you type git log, Git will list the commit ID (a really long list of random numbers and characters), the author (the person who packed it), the date of the commit, and the message for the commit (like “In this commit, I updated my lucky shirt”).

Borrowing from Others

Up until now, we have just been packing our magic suitcase, but we still have to bring it with us to the train or airport or dirigible to go to our destination. Well, now it’s time to level up the suitcase capabilities. We can use an external repository like a company server or a browser-based tool like GitHub.com to push a copy of our magic suitcase inside every airport, train depot, and landing strip that has internet access (or access to the company server). Here's the sequence: You lay out (add) your contents, pack them (commit) in your suitcase (local repository), then push that suitcase to the internet or network so that you, your cat, and anybody else can grab a copy anywhere and any time they need it. (Don’t worry, you can also set up private external repositories so nobody else has access to your unmentionables).

Photo of cat resting his head on a toy train.
When the Duke loses his train of thought, he tries to cover his tracks. Thanks to Andy Gregorowicz for the original image on Flickr.

Git is pretty useful for tracking what you have done in the past, but it is especially useful when you have more than one person working on the same thing. Maybe some other folks have already traveled to places you are going to go, and they have already packed a pretty awesomely useful suitcase. If someone makes their suitcase available, you can clone it to your own closet, make changes, and then push those changes back to the main suitcase that everyone has access to. That’s really what the GitHub process is: a tool for sharing changes to files.

You will need to know about the remote repositories you want to work with, and have permission to push to those repositories. They are usually in your internal network or in a browser-based Git tool like GitHub. Setting permissions for the Learning VM are beyond the scope of this post, so we are just going to clone from a remote repo and save our changes locally (i.e., copy their suitcase, but not share the changes you made back to the original).

If you go to GitHub.com and start searching for “suitcase” or “magic suitcase,” you might stumble upon a repo called thelongshanx/super_suitcase. We are going to start by just copying, but if you want to contribute to a repository on GitHub, you are going to need a GitHub account1.

To get the repo on to your computer or the Learning VM, make sure your VM network settings are set to bridged2. Next, use the cd command to enter a directory where you would like this repo to live, and type
git clone https://github.com/thelongshanx/super_suitcase.git
Now you have your very own copy of the suitcase to edit, add, rm, and commit to.

Branches, or Why You Have to Specify Master

When you create or clone a repository, that repository is called the origin. There are branches inside each repository, and the first branch is, by default, called the master branch. When you want to push your changes to the master, you type
git push origin master
You can replace “origin master” with a different repository or branch.

Let’s say you’ve decided you need a new wardrobe, but you are not sure what look you are going for. You don’t want to throw away all of the stuff you already have in the master branch, so you are going to create a new branch. When you type
git branch new_look
it creates a new branch called new_look. This is the branch where you will start experimenting with wardrobe changes. To start adding to this branch, you need to type
git checkout new_look
You are now in new_look, and the master branch won’t change as you tinker with new_hats.txt and nautical_themed_pashmina_afghans.txt.

You can create as many branches as you want, but you can have only one checked out at a time.

If you decide that the new_look branch is good enough to become the master, you go back to the master branch with git checkout master, and then type
git merge new_look
That pushes everything in new_look to the master branch.

If, on the other hand, the leopard_print_jumpsuit branch just didn’t work out, you can type git branch -d leopard_print_jumpsuit to banish that jumpsuit forever.

Sharing with Others

Pause for a quick note
Up to this point, we have been pretty self-contained; we’ve made copies and kept them to ourselves. If you want to contribute some code back to the open source world, however, you need an account with a remote repository like GitHub.

However, browsing the internet from the Learning VM isn’t easy. From here on out, if you want to follow along on your laptop, you’ll need to take the hyperlink detours provided.
Carry on

With a Github account, you can search for interesting things on GitHub.com. If, for example, you found thelongshanx/magic_suitcase repo, and you want to copy and/or contribute to it, you should click the fork button GitHub fork button in the top right part of your screen to create a copy in your GitHub account that you can tinker with.

You then clone this copy to your computer almost the same way we did before (make a new directory, cd into it, and type git init) — but you add your login name to give you the power to push changes back up to GitHub. Instead of typing
git clone https://github.com/thelongshanx/super_suitcase.git you type
git clone https://[email protected]/thelongshanx/magic_suitcase.git
You will be asked for your GitHub password to make sure you’re not up to any funny business before you can pull everything down to your working directory. Type in
cd magic_suitcase
to get into the shared Git repository.

After you make any changes and commit them on your computer, you will want to push that new version up to your GitHub repository again. You do this by typing
git push origin master
Remember, wherever you make your copy from is called origin.

If you want to contribute back to the repository you originally cloned from, you need to click on the “pull request” button on the far right of the screen in GitHub. The owner of the repository will receive a notification, and determine whether or not they want to incorporate your changes.

Alternatively, if there is another remote GitHub repository besides origin that you want to share your changes with, you should copy the SSH URL from the bottom right side of the repo’s webpage:

Screenshot of SSH URL on GitHub repo page

Then you add the remote repository with
git remote add duke git://github.com/the_duke/wardrobe.git
Replace “duke” with whatever you would like to call the remote repository, and copy the last part from the SSH URL you got from GitHub. You then push to the remote repo by typing
git push duke master (replacing "duke" with the remote repository's name, of course).

Cheat sheet for making changes in GitHub:

  1. GitHub fork button in GitHub
  2. mkdir <directory name>
  3. cd <directory name>
  4. git init
  5. git clone https://[email protected]/User/Project.git
  6. cd <project>
  7. change, add, commit
  8. git push origin master
  9. click submit pull request in GitHub

Conclusions

It has been a long journey, we have covered a whole lot of stuff, and you should feel very proud for sticking through this whole thing. If your cat’s claws are trimmed, you should give each other a high five.

Photo of cat high-fiving a human.
Thanks to Joachim S. Muller for the original image on Flickr.

If you have worked through this entire tutorial series, you should now be able to do enough of the basic CLI, vim and Git stuff to follow the Learning VM quests, take a Puppet Labs training, or use our online workshops for learning Puppet— and probably lots of other cool stuff, too!

Once you are comfortable using the commands you have learned in this series, you should check out some of the other wonderful resources the internet has come up with. Below are some recommendations.

CLI

Linux & Mac OSX

Get into a terminal

Learning the Shell - A darn good resource to learn Linux, period.

You might also want to print out a few cheat sheets:

Windows (Powershell)

Get instructions for installing and getting started with Powershell.

Also check out the Learn and Library sections on technet.microsoft.com.

Vim

Vim has a built-in tutor that you can access by typing vimtutor -g in the vm command line. It will give you some practice, and teach you the next few steps.

Vimdoc - The manual written by the author of vim, Bram Moolenaar. If you want to jump straight to the review and new stuff, go to this page.

Git

Git Cheat Sheet - A cool interactive cheat sheet to learn the different places where you do things or put things in a Git workflow. It will show you some useful next-level commands, which you can then review more thoroughly with
git help <command name>

Git Tutorial - A good reference for visual learners form Atlassian (which makes Bitbucket, an alternative to GitHub).

Pro Git - The entire Pro Git book written by Scott Chacon. Scott goes into far more depth than what I have covered here, and I would like to personally high-five all the agents of the universe that made this wonderful resource available for free.

Git Help resource - If you ever find yourself wondering what the hell is going on while you are working in one of your git directories, you can type
git help thing-you-don’t-know
For example, git help blame tells you all about the blame command:

Screen of Git Manual that shows description of git-blame command

Troubleshooting

StackOverflow - Seriously, if you don’t have a resident engineer in your kitchen, you should consult this website.

Tiffany Longworth is a business systems analyst at Puppet Labs.

Learn More

  • Missed out on Tiffany's other tutorials about the tools for learning Puppet? Read the intro for a bit of background.
  • The command line interface is a powerful way to interact with your computer, but not intuitively obvious if you're coming from a non-Unix, non-Linux background. Read and follow Tiffany's tutorial.
  • Vim is a text editor that's popular with Linux users. Get familiar with it in this tutorial.
  • Looking for enterprise-level configuration management that's fully tested, scalable and fully supported? Download and try out Puppet Enterprise for free.

  1. Directly below the header Set Up Git, select your operating system and follow the instructions. You'll find more instructions for setting up to work with other people in this same resource. ↩︎

  2. On your computer (not the VM), open up VirtualBox, select the Learning VM, and click “network” about halfway down on the right. In the drop-down menu where it says “connect to:”, select “Bridged”. This tells VirtualBox to share your internet connection. ↩︎

Share via:

This is an excellent tutorial Tiffany! I just did a slide show about Git and GitHub, and silly me, I didn't cover "fork" thoroughly :( - (still learning) However, I love your analogies and storytelling for using Git & GitHub - it helped me so much - thanks, and keep up the good work!

I'm glad you enjoyed it! There are so many different bits of Git & GitHub to address that you have to be pretty picky about what to include in an introduction (I'm not sure I was picky enough!). There's always things you think of or figure out afterwards.

For example, after most of this blog was finished, we came up with another way to explain forking- Someone creates the Star Trek repo and everything is going along and they kill Spock and they un-kill Spock and there's Khan, etc. Then, someone's like "Let's make a fork called JJ Abrams!" So this fork has the same Spock.rb and Uhurah.pp, only in this fork they fall in love.

I enjoyed this article immensely because it takes a technical subject and new concepts but allows any newbie to grasp it. You have a rare and prized talent among geeks. There are many geeks but extremely few who can convey geeky ideas to the technically confused in an appealing, respectful, and fun manner. The illustrations bring it all together like a git sermon on the mount. Thanks for merging imagination and tech-ducation!

The content of this field is kept private and will not be shown publicly.

Restricted HTML

  • Allowed HTML tags: <a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul type> <ol start type> <li> <dl> <dt> <dd> <h2 id> <h3 id> <h4 id> <h5 id> <h6 id>
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.