-
Notifications
You must be signed in to change notification settings - Fork 0
/
03s-using-github.md.erb
145 lines (87 loc) · 7.61 KB
/
03s-using-github.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
---
title: Using Git & GitHub
slug: github
date: 0003/01/02
number: 3.5
level: free
sidebar: true
published: true
photoUrl: http://www.flickr.com/photos/ikewinski/7170807209/
photoAuthor: Mike Lewinski
contents: Learn how to use GitHub to follow along with the book.
paragraphs: 32
---
[GitHub](https://github.com/) is a social repository for open-source projects based around the [Git](http://git-scm.com/) 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](https://github.com/DiscoverMeteor/Microscope/commit/chapter3-2) 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](https://github.com/DiscoverMeteor/Microscope/commit/chapter13-1):
<%= 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](https://github.com/DiscoverMeteor/Microscope/commit/chapter12-2):
<%= 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](http://git-scm.com/downloads). Then **clone** (in other words, download a copy locally) the Microscope repository with:
~~~bash
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:
~~~bash
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:
~~~bash
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):
~~~bash
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:
~~~bash
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.