GitHub for Developers

Training Manual

-v1.0

Table of Contents

Welcome to GitHub for Developers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê1

License. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê1

Getting Ready for Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê2

Step 1: Set Up Your GitHub.com Account . . . . . . . . . . . . . . . . . . . . . . . . . Ê2

Step 2: Install Git. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê2

Using GitHub Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê9

Activity: Creating A GitHub Issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê10

Using Markdown. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê10

Understanding the GitHub Flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê12

The Essential GitHub Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê12

Branching with Git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê13

Branching Defined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê13

Activity: Creating A Branch with GitHub . . . . . . . . . . . . . . . . . . . . . . . . . Ê13

Local Git Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê15

Checking Your Git Version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê15

Working Locally with Git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê19

Creating a Local Copy of the repo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê19

Our Favorite Git command: git status. . . . . . . . . . . . . . . . . . . . . . . . Ê20

Using Branches locally. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê20

Switching Branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê20

Activity: Creating a New File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê21

The Two Stage Commit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê21

Collaborating on Your Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê24

Pushing Your Changes to GitHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê24

Activity: Creating a Pull Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê25

Merge Explained . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê29

Merging Your Pull Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê30

Cleaning Up Your Branches. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê30

Viewing Local Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê32

Different Commands for Viewing Changes. . . . . . . . . . . . . . . . . . . . . . . Ê32

Viewing Local Project History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê33

Using Git Log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê33

Fixing Commit Mistakes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê34

Changing Commits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê34

Streamlining Your Workflow with Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . Ê35

Workflow Review: Updating the README.md . . . . . . . . . . . . . . . . . . . . . Ê37

Reverting Commits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê38

How Commits Are Made . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê38

Safe Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê39

Reverting Commits with git revert . . . . . . . . . . . . . . . . . . . . . . . . . . Ê39

Resolving Merge Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê41

Local Merge Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê41

Remote Merge Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê42

Exploring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê42

Helpful Git Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê43

Reset Soft . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê46

Merge Strategies: Rebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê51

About Git rebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê51

Activity: Git Rebase Practice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê52

Appendix A: Talking About Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê53

Discussion Guide: Team Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ê53

Welcome to GitHub for Developers

Today you will embark on an exciting new adventure: learning how to use

Git and GitHub.

As we move through today’s materials, please keep in mind: this class is

for you! Be sure to follow along, try the activities, and ask lots of

questions!

License

The prose, course text, slide layouts, class outlines, diagrams, HTML, CSS,

and Markdown code in the set of educational materials located in this

repository are licensed as CC BY 4.0. The Octocat, GitHub logo and other

Getting Ready for Class

While you are waiting for class to begin, please take a few minutes to set

up your local work environment.

For this class, we will use a public account on GitHub.com. We do this for

a few reasons:

• We don’t want you to "practice" in repositories that contain real code.

• We are going to break some things so we can teach you how to fix

them. (therefore, refer to #1 above)

If you already have a github.com account you can skip this step.

Otherwise, you can set up your free account by following these steps:

1. Access GitHub.com and click Sign up.

2. Choose the free account.

3. You will receive a verification email at the address provided.

$ git --version

You should see something like this:

$ git --version

git version 2.6.3

Anything over 1.9.5 will work for this class!

Downloading and Installing Git

If you don’t already have Git installed, you have two options:

1. Download and install Git at www.git-scm.com.

2. Install it as part of the GitHub Desktop package found at

desktop.github.com.

• If you are working on Windows, you can use PowerShell or Git

Shell which is installed with the Git package.

• If you are working on a Mac or other Unix based system, you can use

the terminal application.

Go ahead and open your command line application now!

Step 3: Set Up Your Text Editor

For this class, we will use a basic text editor to interact with our code.

Let’s make sure you have one installed and ready to work from the

command line.

Pick Your Editor

• Sublime

• Notepad or Notepad++

If you do not already have a text editor installed, go ahead and download

and install one of the above editors now!

Your Editor on the Command Line

After you have install an editor, confirm you can open it from the

command line. If you are working on a Mac, you will need to Install Shell

Commands from the Atom menu, this happens as part of the installation

process for Windows.

If installed properly, the following command will open the atom text editor:

@mention

#975

:smiley:

Understanding the GitHub Flow

In this section, we will discuss the collaborative workflow enabled by

GitHub.

GitHub lives on a branch. By convention, the "blessed" or "canonical"

version of your project lives on a branch called master.

When you are ready to experiment with a new feature or fix an issue, you

create a new branch of the project. The branch will look exactly like

master at first, but any changes you make will only be reflected in your

branch. Such a new branch is often called a "feature" branch.

As you make changes to the files within the project, you will commit your

changes to the feature branch.

When you are ready to start a discussion about your changes, you will

open a pull request. A pull request doesn’t need to be a perfect work of art

Branching with Git

The first step in the GitHub Workflow is to create a branch. This will allow

us to separate our work from the master branch.

This keeps your the code on your master branch safe while you

experiment and fix issues.

Let’s learn how you can create a new branch.

Activity: Creating A Branch with GitHub

Earlier you created an issue about a change you would like to introduce

into the project. Let’s create a branch that you will use to add your file.

Follow these steps to create a new branch in the class repository:

1. Navigate to the class repository.

2. Click the branch dropdown.

3. Enter the branch name 'firstname-lastname-hometown'.

4. Press Enter.

will be applied to this new branch.

automatically assumes you want to see the items on the

master branch. If you want to continue working on your

branch, you will need to reselect it using the branch

dropdown.

Local Git Configuration

In this section, we will prepare your local environment to work with Git.

Checking Your Git Version

First, let’s confirm your Git Installation:

$ git --version

$ git version 2.7.0

If you do not see a git version listed or this command returns an error, you

--global

--local



The default value for git config is --local.

Viewing Your Configurations

$ git config --list

Configuring Your User Name and Email

$ git config --global user.name "First Last"

$ git config --global user.email "[email protected]"



Git uses the config settings for your user name and email

address to generate a unique fingerprint for each of the

commits you create.

$ git config --global core.editor "atom --wait"

Next, we will add the default text editor git will use when you need to edit

above will work.

If you would like to use a different editor you can find additional

instructions at https://help.github.com/articles/associating-text-editors-

with-git/

Configuring autocrlf

$ //for Windows users

$ git config --global core.autocrlf true

$ //for Mac or Linux users

$ git config --global core.autocrlf input

Different systems handle line endings and line breaks differently. If you

Working Locally with Git

If you prefer to work on the command line, you can easily integrate Git into

your current workflow.

$ git status

• guides.github.com/features/mastering-markdown/ An interactive

guide on using Markdown on GitHub.

Editing Files on GitHub

Since you created the pull request, you will be notified when someone

adds a comment. In this case, the comment may ask you to make a

To edit a pull request file, you will need to access the Files Changed view.

Click the edit icon to access the GitHub file editor.

directs us to commit our changes to the same branch. Choose the option

to Commit directly to your branch and click Commit changes.



If you want to see what was changed in a specific commit,

you can go to the Commits tab and click on the Commit ID

you would like to view.

Merging Pull Requests

Now that you have made the requested changes, your pull request should

be ready to merge.

When you merge your branch, you are taking the content and history from

your feature branch and adding it to the content and history of the master

branch.

team to ensure consistency. Still others say it can be

anyone other than the person who created the pull request.

This is a discussion you should have with the other

members of your team.

First, let’s use some emoji to indicate we have checked over the Pull

Request and it looks good to merge. We like to use :+1: :ship: or :shipit:.

1. Open the Pull Request to be merged

2. Open the Conversation view

3. Scroll to the bottom of the Pull Request and click the Merge pull

When you merged your Pull Request, you deleted the branch on GitHub,

but this will not automatically delete your local copy of the branch. Let’s go

back to our Terminal and do some cleanup.

$ git checkout master

$ git pull ¬

$ git branch --all ¬

①

②

this command to ensure all of the changes on our feature branch have

been merged to master before we delete the branch.

To delete the local branch, type the following command:

$ git branch -d <branch-name>

If you type git branch --all again, you will see that your local branch

is gone but the remote tracking branch is still there. To delete the remote

tracking branch, type:

$ git pull --prune



If you would like pruning of the remote tracking branches

Viewing Local Changes

Now that you are familiar with the basic workflow, let’s explore some of

the powerful Git and GitHub features that will help you work with your

the working and staging directories and what is in your history.

$ git diff

$ git diff --staged

$ git diff HEAD

$ git diff --color-words

Viewing Local Project History

In this section, you will discover commands for viewing the history of your

project.

When you clone a repository, you receive more than just the files in that

the repository. You also receive the history of all of the commits made in

Let’s take a look at some of the option switches you can use with the log

command to customize your view of the project history.

$ git log

$ git log --oneline

$ git log --oneline --graph

$ git log --oneline --graph --decorate

return to the command prompt.

Fixing Commit Mistakes

In this section, we will begin to explore some of the ways Git and GitHub

can help us shape our project history.

Commit amend allows us to fix mistakes in our last commit. Two of the

most common uses are:

• Re-writing commit messages

• Adding files to the commit

When you are adding files to the previous commit, the files to be added

should be in the staging area when you type the git commit --amend

command.

$ git commit --amend



You can actually amend any data stored by the last commit

such as commit author, email, etc.

Streamlining Your Workflow with Aliases

So far we have learned quite a few commands. Some, like the log

commands, can be long and tedious to type. In this section, you will learn

An alias allows you to type a shortened command to represent a long

For example, let’s create an alias for the log command we learned earlier.

Workflow Review Project: GitHub Games

In this section, we will complete a project using the GitHub Flow.

User Accounts vs. Organization Accounts

There are two major account types in GitHub, user accounts and

organization accounts. While there are many differences in these account

types, on of the more notable differences is how you handle permissions.

User Accounts

Helpful Git Commands

In this section, we will explore some helpful Git commands.

Moving and Renaming Files with Git

2. Change the background url to (images/texture.jpg).

3. Change the timing for the game to speed it up or slow it down.

4. Type git status.

5. Type mkdir images.

6. Type git mv texture.jpg images/texture.jpg.

Staging Hunks of Changes

Crafting atomic commits is an important part of creating a readable and

informative history of the project.

1. Type git status.

Rewriting History with Git Reset

In this section, you will learn how to re-write history with Git.

Understanding Reset

Sometimes we are working on a branch and we decide things aren’t going

quite like we had planned. We want to reset some, or even all, of our files

to look like what they were at a different point in history. We can do that

with git reset.

Remember, there are three different snapshots of our project at any given

time. The first is the most recent commit. The second is the staging area

(also called the index). The third is the working directory (i.e. whatever you

currently have saved on disk). The git reset command has three

modes, and they allow us to change some or all of these three snapshots.

It also helps to know what branches technically are: each is a pointer, or

reference, to the latest commit in a line of work. As we add new commits,

the currently checked-out branch "moves forward," so that it always points

to the most recent commit.

mixed

Next we will try out each of these options.

Creating a Local Repository

Since git reset rewrites history, you should avoid using it on commits

that have already been made public (e.g. pushed to the repository on

GitHub).

To avoid teaching you bad habits, we will create a practice repository. This

time, we will start the repository locally, from the command line.

To prepare for this activity, you will need to create four files and commit

each separately so your file directory looks like this:

$ ls

file1.md

file2.md

file3.md

file4.md

README.md

And your history looks like this:

Now that your repository is set up, let’s try our first reset.

1. Use the log alias we created earlier to look at the history of our project.

2. Identify the current location of HEAD.

3. We want to go back two commits in our history so we will type git

reset --soft HEAD~2.

4. Type git status. The changes we made in the last two commits

should be in the staging area waiting to be committed.

5. Using the log command, we can see that the HEAD is now sitting two

commits earlier than it was before we used git reset.

6. Go ahead and re-commit these changes with git commit -m

Reset Mixed

After the soft reset, your file directory should still look like this:

To prepare for this activity, you will need to create four files and commit

$ ls

file1.md

file2.md

file3.md

file4.md

README.md

Next we will try the mixed reset:

1. Once again, we will start by viewing the history of our project.

2. This time we only want to go back one commit in history so we will

type git reset HEAD~ OR git reset <SHA>.

3. Type git status. The changes we made in the last commit have

been moved back to the working directory.

4. This time, we will need to git add the files to the staging area before

we can commit them.

5. Go ahead and re-commit the files with git commit -m "another

reset example".

2. This time we reset to the point in time where the only file that existed

was the README.md. Type git reset --hard <SHA>.

3. Type git status. Notice your working directory is clean.

4. Viewing the history of your project will reveal a single commit.



Remember, git reset --hard is a destructive

command. Don’t use it unless you really want to discard

your changes.

Does Gone Really Mean Gone?

The answer: It depends!

Type the command git reflog.

Cherry Picking

We just learned how reflog can help us find local changes that have been

discarded. So what if:

Cherry picking allows you to pick up a commit from one branch of the

project and move it to your current branch. Right now, your file directory

Merge Strategies: Rebase

In this section, we will discuss another popular merge strategy, rebasing.

About Git rebase

The rebase command enables you to modify your commit history in a

variety of ways. For example, you can use it to reorder commits, edit them,

squash multiple commits into one, and much else.

To enable all of this, rebase comes in several forms. For today’s class,