Using GitHub

GitHub is a social repository for open-source projects based around the Git version control system, and its primary function is to make it easy to share code and collaborate on projects. But it's also a great learning tool. In this sidebar, we'll quickly go over a few ways you can use GitHub to follow along with Discover Meteor.

This sidebar assumes you're not that familiar with Git and GitHub. If you're already comfortable with both, feel free to skip on to the next chapter!

Being Committed

The basic working block of a git repository is a commit. You can think of a commit as a snapshot of your codebase's state at a given moment in time.

Instead of simply giving you the finished code for Microscope, we've taken these snapshots every step of the way, and you can see all of them online on GitHub.

For example, this is what the last commit of the previous chapter looks like:

<%= screenshot "s3-1", "A Git commit as shown on GitHub." %>

What you see here is the “diff” (for “difference”) of the post_item.js file, in other words the changes introduced by this commit. In this case, we created the post_item.js file from scratch, so all its contents are highlighted in green.

Let's compare with an example from later on in the book:

<%= screenshot "s3-2", "Modifying code." %>

This time, only the modified lines are highlighted in green.

And of course, sometimes you're not adding or modifying lines of code, but deleting them:

<%= screenshot "s3-3", "Deleting code." %>

So we've seen the first use of GitHub: seeing what's changed at a glance.

Browsing A Commit's Code

Git's commit view shows us the changes included in this commit, but sometimes you might want to look at files that haven't changed, just to make sure what their code is supposed to look like at this stage of the process.

Once again GitHub comes through for us. When you're on a commit page, click the Browse code button:

<%= screenshot "s3-5", "The Browse code button." %>

You'll now have access to the repo as it stands at a specific commit:

<%= screenshot "s3-6", "The repository at commit 3-2." %>

GitHub doesn't give us a lot of visual clues that we're looking at a commit, but you can compare with the “normal” master view and see at a glance that the file structure is different:

<%= screenshot "s3-7", "The repository at commit 14-2." %>

Accessing A Commit Locally

We've just seen how to browse a commit's entire code online on GitHub. But what if you want to do the same thing locally? For example, you might want to run the app locally at a specific commit to see how it's supposed to behave at this point in the process.

To do this, we'll take our first steps (well, in this book at least) with the git command line utility. For starters, make sure you have Git installed. Then clone (in other words, download a copy locally) the Microscope repository with:

git clone https://github.com/DiscoverMeteor/Microscope.git github_microscope

That github_microscope at the end is simply the name of the local directory you'll be cloning the app into. Assuming you already have a pre-existing microscope directory, just pick any different name (it doesn't need to have the same name as the GitHub repo).

Let's cd into the repository so that we can start using the git command line utility:

cd github_microscope

Now when we cloned the repository from GitHub, we downloaded all the code of the app, which means we're looking at the code for the last ever commit.

Thankfully, there is a way to go back in time and “check out” a specific commit without affecting the other ones. Let's try it out:

git checkout chapter3-1
Note: checking out 'chapter3-1'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:

  git checkout -b new_branch_name

HEAD is now at a004b56... Added basic posts list template and static data.

Git informs us that we are in “detached HEAD” state, which means that as far as Git is concerned, we can observe past commits but we can't modify them. You can think of it as a wizard inspecting the past through a crystal ball.

(Note that Git also has commands that let you change past commits. This would be more like a time traveller going back in time and possibly stepping on a butterfly, but it's outside the scope of this brief introduction.)

The reason why you were able to simply type chapter3-1 is that we've pre-tagged all of Microscope's commits with the correct chapter marker. If this weren't the case, you'd need to first find out the commit's hash, or unique identifier.

Once again, GitHub makes our life easier. You can find a commit's hash in the bottom right corner of the blue commit header box, as shown here:

<%= screenshot "s3-4", "Finding a commit hash." %>

So let's try it with the hash instead of a tag (if this specific hash doesn't work, feel free to get another one from GitHub):

git checkout b1280aa8affdb9f4ca5dab5f84d0f9878fc2f67d
Previous HEAD position was a004b56... Added basic posts list template and static data.
HEAD is now at c7af59e... Augmented the postsList route to take a limit

And finally, what if we want to stop looking into our magic crystal ball and come back to the present? We tell Git that we want to check out the master branch:

git checkout master

Note that you can also run the app with the meteor command at any point in the process, even when in “detached HEAD” state. You might need to run a quick meteor update first if Meteor complains about missing packages, since package code is not included in Microscope's Git repo.

Historical Perspective

Here's another common scenario: you're looking at a file and notice some changes you hadn't seen before. The thing is, you can't remember when the file changed. You could just look at each commit one by one until you find the right one, but there's an easier way thanks to GitHub's History feature.

First, access one of your repository's files on GitHub, then locate the “History” button:

<%= screenshot "s3-8", "GitHub's History button." %>

You now have a neat list of all the commits that affected this particular file:

<%= screenshot "s3-9", "Displaying a file's history." %>

The Blame Game

To wrap things up, let's take a look at Blame:

<%= screenshot "s3-10", "GitHub's Blame button." %>

This neat view shows us line by line who modified a file, and in which commit (in other words, who's to blame when things aren't working anymore):

<%= screenshot "s3-11", "GitHub's Blame view." %>

Now Git is a fairly complex tool – and so is GitHub –, so we can't hope to cover everything in a single chapter. In fact, we've barely scratched the surface of what is possible with these tools. But hopefully, even that tiny bit will prove helpful as you follow along the rest of the book.