Git Training @ 352 Media

Before you start the training

Sign up for an account at Github and send the username to nrosental@352media.com
Set up Git
Follow the steps on this page to generate SSH keys and add them to your account.
(optional) Install Github app for Mac or Windows
(optional) go through the Try Git course

A few words before we start

This training assumes you have a Mac computer. If you don't, it'll still be useful and you will be able to follow the command line examples.

Most of the training focuses on using Git from the command line, with a repository on Github. We'll also cover some GUI options, but the intention is for you to learn the basics of the CLI.

For Windows Users Only

Download the Git installer
Run through the installation (see the options in the screenshots below.)

The installer comes bundled with two applications, Git GUI and Git Bash. You can use Git Bash for all the command line examples in this training document. Use Git GUI at your own risk.

Terms

Some of the terms you'll hear (repeatedly) during the training session:

Git: Duh! Git is a versioning system much like SVN. It allows teams (and even solo developers) to work on the same code base in a much more organized manner. The main difference with SVN is that it's decentralized (i.e. every collection of the code is hirerchally equal.)
Repo: The collection of files that make up "the code."
Branch: A version of your code that you can safely work on without messing up everyone else's work.
Master: The main branch. It can be called anything, but everyone refers to it as master by convention.
Origin: The name usually given to the remote repo (in our case, Github.) Again, this is a widely used convention, but not a requirement.
Merge: Adding the code from one branch onto another.
Push: A Git command that sends your code from your local repo, to a remote repo.
Pull: A Git command that brings the code in a remote repo to your local repo.
Commit: Once you like what you coded, make it stick.
Clone: Make a copy of a remote repo.

There are many more terms, but you'll sure hear this ones a lot.

Part I - Working with the CLI

Let's Get a Repo

In the future you'll likely create repos for your own projects on Github, but for this training session I've already took care of that.

Open a terminal and issue the following commands

git clone git@github.com:nicdev/git-training.git
cd git-training 
ls

The first command copies the repo from Github into your local machine, the rest is just navigating to the local directory and viewing the files.

Branching Out

When you are working on a new feature, you will want to branch out. Once you branch, any change you make to your code won't affect anyone else. Once you like how your code works, you can merge your changes back into the master branch.

Try it out

git checkout -b name-your-branch

checkout is the command to switch branches, -b indicates to create a new one, and name-your-branch is a placeholder; please use your own name.

Holy awesomeness Batman! You just created your own branch. Now you are free to change things around with no consequences whatsoever. I don't think you can say the same about most everything else in your life.

Go ahead. Pick any text editor and make a change to index.html. Add a <div></div> or some <h1>Hello World</h1> or something (don't forget to save the file.)

Don't Be Afraid of Commitment

Now that you did your thing, you'll want to make sure your code sticks.

git status
git add -A .
git commit -m "Insert a descriptive message about your code change here. Wit optional."

The first command is so that you see what files changes and it's not really needed to commit your code. The second command adds your changes; the -A means ALL, the . is like saying "add it all from this directory on down." The third and last command is the one that actually makes the changes part of the code base.

Now back to the terminal and do

git checkout master

Look at index.html again and OMG! all your changes are gone. See what I mean by no consequences? Jump back to the terminal and check out your own branch

git checkout name-your-branch

Boom! Your changes are back. Now back to the terminal and do

git checkout master

Look at index.html again and OMG! all your changes are gone. See what I mean by no consequences? Jump back to the terminal and check out your own branch

git checkout name-your-branch

Boom! Your changes are back.

Push It!

git push -u origin name-your-branch

This will send your branch up to Github. The -u switch isn't strictly necessary, but it tells your repo that the local branch name-your-branch corresponds to the remote branch name-your-branch. In the next lesson you'll learn why this is useful.

Browse to the repo on Github and look for your branch.

Be Polite, Make a Request

At this point you probably notice that you can push directly to the master branch. DON'T DO IT! The master branch is the one everyone will consider as clean and up to date. Pushing directly to it is not nice. Instead, make a pull request.

Go back to Github, and click on Pull Requests or follow this link. Then click on the New Pull Request button.

Make sure the "base" field says master and the "compare" field is name-your-branch

There's a lot going on here. Take a minute to explore. You'll see the number of commits you're merging, how many files have changed, a diff of files that have changes and a bunch more.

Once you are satisfied with what you see, click on the Create Pull Request button.

If everything is well with the world, you'll see the green "Able to merge" message.

Go ahead and click on "Send pull request." But you're not done quite yet. At this point, the code needs to be merged (accepted) into the master branch. At this point you can click on the "Merge pull request" button.

If there are conflicts, you'll see this instead (I'll show you how to fix that later)

This may seem like a lot of effort for getting the code merged, but it helps keep conflicts at bay and once you get used to it, it's actually very quick.

Doing it Right

In the previous step we just sent in the pull request and hoped for the best. The right way to go about it would be to make sure you don't have any conflicts before sending the request.

Jump back on the terminal, then make some more changes to any of the files, create new files. Go nuts! Once you are done, go through the add/commit process.

git add -A .
git commit -m "Informative message here"

Now, before you push it up, make sure your code can merge properly with master.

git pull origin master

What you are doing here is bringing in the code from the remote master branch into your own.

If something fails to automatically merge, you will be notified

This can be frustrating, but Git makes it very clear where to find the conflicts. In this case, the same part of index.html was changed so Git isn't sure which one to use. The conflicted file looks like this

The code immediately following HEAD is our local code, the code between ======== and 657510f14da0d146da3e00299d59be9a7a5c24ac is what we pulled from master

HEAD refers to your working state, 657510f14da0d146da3e00299d59be9a7a5c24ac is a unique identifier for the commit you tried to merge in.

To fix this, we can manually edit the code, or use a diff tool. In this case, I'm just going to fix it up manually. The code now looks like this:

Go through the add/commit motions

git add -A .
git commit -m "all fixed up"

Now when I pull from the remote master Git already knows which way it should merge.

git pull origin master
git push origin name-your-branch

When you do the pull request you know it will get an all green because you've already merged the latest from master

Sum It Up

We just covered the basics that will get you up and running with Git. Let's do a recap.

Branch out and work on your code
Pull the latest from master (or the main branch you're working against.)
Push your own branch up to Github
Submit a pull request
Accept the pull request

Part Deux - Ze GUI

Let's look at Github for Mac.

After it's installed, you will see all the organizations you are part of, a list of available remote repos, and a shortcut to the local repos you've added to the app.

Add the local repo we've been working on

Creating a New Branch

Pushing to Remote

Clicking publish is the equivalent of pushing the branch to the remote repo.

Now that it's been published (pushed) let's make some code changes. Once you are done changing the code, hop back on the app and look at the "Changes" section.

Committing Changes

Click the commit button so your changes "stick." You should commit often. There's always a way of rolling back, and the more commits you have the easier it is to roll back to a desired state should something go wrong.

Once done, click on the "sync" button. That will push your branch up. If it's already been pushed, it'll push the changes to its remote counterpart.

GUI or CLI, Everyone Requests

Ultimately go back to Github and submit a pull request.

Extras

Ignore

A small but extremely necessary feature is the .gitignore file. This file tells Git to not add certain files to your repo. Let's try it out.

Create a file in the root directory and call it whatsup.people

Open the .gitignore file and add a line that *.people. This will ignore all files with the extension .people.

Delete

Once you are done with a branch, whether its code has been committed to another branch, or you are done experimenting, you should delete it.

Delete local

git branch -D old-branch

Delete remote (notice the : in front of the branch name)

git push :old-branch

The branch command can also be used to see what branches you currently have, and which one you are currently using.

git branch

Save a Step

You can add and commit in one command

git commit -am "I'm committing in one step"

Halp!

You can learn more about all git commands by issuing a help call.

git help 
git help commit 
git help merge
git help add
...

The end all, be all resource for Git Git SCM

How to Deal With Merge Conflicts

And of course the usual Google -> Stack Overflow path.

Part III - How We Do Git

There are many established workflows when it comes to Git. We will be using what's known as the Feature Branch Workflow.

Branch Naming Convention

The standard naming convention we'll use is as follows: [task number]-[descriptive name]. For our example we'll use 12345-logo-alignment_

Task number is the particular task you're working on as assigned in TFS.
Keep the description short but descriptive.
Use dashes as separators.

Important Branches

There are two permanent branches that should be treated with the utmost care: master and development. The former is the code that is in production, the latter is the code for the current sprint.

Version Numbers

We need to define the current major version number, but since the product is still in beta, I suggest we use 0.x. Once we get our of beta we can start the 1.x and upgrade as needed. The minor version should be the sprint number. So for example, the current release should be 0.16 (beta major, sprint #16)

Rules of the Road

Never push directly to master
Solve your conflicts locally
Use descriptive commit messages

The scenario

The sprint has been set, there are a few new features and some bugs to work on. You've decided to take on backlog item #12345 which happens to be a bug.

Make sure your code is up to date.

git checkout development
git pull origin development

Start a new branch.

git checkout -b bug-12345-logo-alignment

Write code, commit it (as many times as necessary)

git add -A .
git commit -m "Re-aligned logo as per inVision mockup"

...

git add -A .
git commit -m "Modified LESS variables to share between footer and gheader logos"

Pull down the latest code and verify there aren't any conflicts

git pull origin development
git push -u origin bug-12345-logo-alignment

Submit a pull request from 12345-logo-alignment to development

Deployment Time

This only applies to designated "deployers." These are the guardians of the master branch and ensure that only clean builds get pushed to production.

Send pull request from development into master.
Verify there aren't any conflicts.
Create a tag and push it (tags need to be explicitly pushed.)

git pull origin master
git tag -a v0.16 -m "completed sprint #16, deployment scheduled for 4/22/14 @ 1:00pm"
git push origin v0.16

Deploy
Profit!

nicdev / git-training