Commit 568df444 authored by Git for Teams's avatar Git for Teams

Lessons were renumbered to match O'Reilly conventions.

Intro is actually lesson "zero" by the ORM convention. Shuffling all
lessons so recordings match any numbers used in the publications.
parent 7d9a8dc7
# Introduction
## Welcome and Set-up
I've been teaching version control for almost as long as I've
been using it. Over the years I've refined how I've taught this
topic, and have learned a lot about what doesn't work in the
traditional ways we currently teach version control. In this
learning series, I'm going to be doing things a little bit
differently. Instead of focusing on the commands you'll be
running, I'm going to try and start with WHY you'd want to do
something, and then show you HOW you'd go about implementing
the solution.
As a developer, I've learned a lot of little hacks to help me
be more efficiently. I'm still not fantastic at the command
line. I haven't replaced myself with a tiny shell script, but I
am very comfortable working from the command line. I enjoy the
elegance of not having to click eleventy buttons on eight
screens, and instead just issuing a few commands. I've also
found it's a lot easier to write cheat sheets for the command
line than for a GUI. And there seem to be a lot more answers on
Stack Overflow, but that could just be Google optimizing the
answers for the types of things I'm normally looking for.
As this learning series is a "watch over my shoulder" type of
series, we're going to work in my usual fashion: from the
command line. Unlike watching over my actual shoulder, you'll
be able to pause the video, and loop back over anything I've
said if you missed it the first time.
Throughout this learning series I'm going to assume you have a
number of things setup and ready to go. I'll be working from
the command line. If you prefer to use a GUI, you'll need to
figure out how these commands map onto your software
application. I encourage you to try the command line with me.
One of the reasons why people like having a GUI is that it
helps them to create a visual map of what they're working on.
Instead of relying on software to provide this map, I'll be
using diagrams. I encourage you to grab a drawing tool (paper
and pen work great!) and sketch along with me. Creating your
own diagrams will help the learning process as the movement
helps to build yet another neural pathway to the information.
### Lesson Objectives
By the end of this lesson, you will be prepared for learning Git.
### Self-Check
I have assembled the following:
- Drawing tools for diagrams (pencil/pen and paper is fine!).
- Git is installed at the command line.
### Lesson Summary
Working at the command line is universal. It may require some additional
configuration for Windows, but it allows us to share commands across
operating systems without having to worry about the discrepancy between
GUIs.
When learning new topics, creating a drawing to represent information will
help you to create the neural pathways which make it easier to recall the
information later on.
## Warm-up Exercise
Being able to describe in words, or with pictures, how
something works, converts it from the abstract, into something
which can be programmed. Any time we are able to use words in a
linear fashion (i.e. talking through a problem), we are able to
find the corresponding commands that we'll need to issue to
make our process work. If you are not able to diagram, or
describe your problem, it will be near impossible to find the
matching commands you need to run.
Sketch the assembly line for your code as it exists currently, or as
you think you would like it to work. Examples: centralized, peer
review, automated gate keeper.
### Lesson Objectives
By the end of this lesson, you should be able to sketch the
relationship between the people on your team, and the tasks they
perform.
### Self-Check
Does your diagram summarize how your team currently works
together (or how you'd like them to work together)?
### Summary
There are three fairly common workflows for teams:
- centralized: code checked into a single, central server
- peer review: a person checks the code before merging it to
a main development branch
- automated gate keeper: a test suite checks the code before
merging it into a main development branch
These examples aren't exhaustive, and they aren't mutually
exclusive. Your workflow may incorporate bits and pieces of
these, or use something different. We'll work on refining your
understanding of how these diagrams relate to git commands
throughout the rest of this learning series.
# Getting Started with Hosted Git Repositories
Most of the people I've worked with are starting out with a project
they need to collaborate with. They aren't starting with an empty
folder, but rather with an existing project. I personally find it
easier to tinker with something rather than stare at a blank screen.
So the first thing we're going to do is set you up with a practice
repository that I've created. You won't be able to edit *my* copy of
the project, but you will be able to make edits to your own copy.
## Overview of permission strategies
Let's start with a review of permission strategies and the way a
project can be setup with Git.
Overview of permission strategies:
- *Centralized*. Commonly seen for centralized systems, such as
Subversion. In this system, everyone is committing into the
same repository on a single machine. When you're working with
a distributed version control system, such as Git, you're
actually using a centralized model. This model often has
finer grained access on who can make a commit, and where they
can commit to.
- *Patched*. The first step away from a centralized system, is
to work in patch files. In this case, there is still a
central, canonical place where code is stored, like in the
centralized system. But in this case, very few people are
allowed to commit to the central repository. Instead, code
changes are shared as patch files. This permission strategy
is lesson common today, but it's still used by the Linux
kernel team, and by Drupal.
- *Forked*. Most open source projects will use a forking
permission strategy. In this case, we are finally seeing the
difference (and power) of a distributed version control
system. In a forking workflow, there are multiple copies
of the repository. I have my copy; you have your copy. And
through a social convention, we decide which copy is the
canonical (or primary) source. This permission strategy is
used to limit who is allowed to make commits back into the
canonical source for a project. In other words: it is a
limiting strategy.
- *Branched*. Whereas a forking strategy gives very limited
access to a small number of people, a branching strategy is a
permissive strategy. The branching strategy is typically used
by internal teams (and the teams responsible for the
canonical repository of a bigger project). In this strategy
it is only by convention that people choose which branches
they want to save their commits to. There are no restrictions
once you have access.
Permission strategies and branching strategies are often
conflated in articles about version control. This can make it
confusing. When examining a diagram, take a look at the symbols
used. If there are dots representing individual commits, you
are probably looking at a *branching strategy* diagram. We'll
get to those a bit later in the series.
### Lesson Objectives
By the end of this lesson, you will be able to identify four
different permission strategies used for version control, and
explain in each strategy, who may make commits to a repository.
### Self-Check
Identify the reasons why the identified strategies was selected:
- Large open source project may use a forking workflow.
- An internal team project uses a branching workflow.
### Lesson Summary
There are four main permission strategies used with distributed version
control systems:
- Centralized is how you work at your own work station. Changes are saved
into your local repoitory, unlike in a centralized *system* where the
changes were saved into a remote repository.
- Patching strategy is where each person has a local repository, and shares
their work with others by sending patch files, which identify how to
"patch up" a repository with a common ancestor so it looks like the work
the developer as done in their own copy of the repository.
- Forked strategy is where each person creates a copy of the canonical
repository, and maintains a connection to it. Proposed changes are made by
submitting a "pull request" or "merge request" to the upstream project.
- Branching strategy is where every person on the team has write-access to
the project. Instead of waiting for a pull request (or merge request) to
be accepted, they are able to save their changes directly to the
repository, without additional permission from another person.
## Creating a GitLab Account
GitLab is a free code hosting platform which allows you to create private,
and public repositories. It's also an open source product you can install
behind your own firewall if you're working with a large team. It's not the
most popular system out there, but I believe it offers the most flexibility
to the widest range of people watching these videos. We'll get started with
GitLab, and later in the lessons, I'll show you how to migrate your project
to GitHub, which is currently one of the most popular code hosting platforms
for open source projects. Git is distributed because work can be easily
shared across multiple hosting systems. Create a GitLab account to store
your first remote repository.
### Lesson Objectives
By the end of this lesson, you will be able to create an account on GitLab.
### Self-Check
Ensure you have a GitLab account before proceding to the next lesson.
### Summary
1. Navigate to www.gitlab.com.
2. At the bottom of the screen locate the link to [create an
account](https://gitlab.com/users/sign_up).
3. Complete the on-screen instructions to create your account.
### Gotchas
GitLab releases new software every month. If the interface is significantly
different, check the instructions on GitForTeams.com. I have made a backup
of GitLab which uses same interface as these video lessons.
## Adding Your SSH Keys
SSH keys are a way to identify trusted computers, without using
passwords. When you are using code hosting systems, these SSH
keys will allow you to effectively "log in" to the system, and
either retrieve, or save, code as if you had logged into to your
account.
### Lesson Objectives
By the end of this lesson, you will be able to locate, and add
your SSH keys to GitLab. If do not have SSH keys already, you
will also be able to create a new SSH key pair.
### Self-Check
Your SSH public key has been uploaded to GitLab.
### Summary
Locate, or Generate SSH Keys:
1. At the command line, run: `cat ~/.ssh/id_rsa.pub`. If there is a blob of
text printed to the screen beginning with `ssh-rsa` or `ssh-dsa`, skip
the next step.
2. To generate new keys, run: `ssh-keygen -t rsa -C "$your_email"`
(replace with your actual email)
3. To display your new public key, run: `cat ~/.ssh/id_rsa.pub`.
4. Copy the text for your public key.
Add Your Public Key to GitLab:
1. Log in to GitLab.
2. Navigate to your account (top right).
3. Locate and click on the tab for [SSH keys](https://gitlab.com/profile/keys).
4. Click "Add SSH Keys".
5. In the form, paste your SSH public key. (The title is optional.)
6. Click save.
## Forking Your First Project
We are forking so that you can upload your changes to your own
repository. If you cloned from this project directly to your computer
you wouldn't be able to upload your changes to the project (only
“privileged” users can do that).
### Lesson Objectives
By the end of this lesson, you will be able to create a fork of a
remote repository.
### Self-Check
In your GitLab account, you should now have a new project with its
upstream set to `gitforteams/workshop`.
### Summary
Fork the GitLab sample project:
1. Navigate to the project page:
https://gitlab.com/gitforteams/workshop
2. Locate and click on the
button labeled "fork".
https://gitlab.com/gitforteams/workshop/fork
Tada.
## Privatizing Your Repository
Adjust the visibility of your forked repository to PRIVATE.
Although this is completely optional, a lot of people feel more
comfortable making mistakes when they know no one will see
them.
Private repositories are also useful if you want to use GitLab for
private projects, such as client work, and don't want others to be able
to see the code you are creating.
### Lesson Objectives
By the end of this lesson, you will be able to alter the permission
settings of your repository so that no one else can view its contents.
### Self-Check
When you log out of GitLab, are you still able to navigate to your
project page and see your work?
### Summary
Adjust the settings of your forked repository so that the project is
private.
1. Navigate to your account page (click the avatar, top right).
2. From the right sidebar, select the project you've just forked.
3. Click the "settings" tab.
4. Scroll down and change the visibility settings to "Private".
5. Scroll to the bottom of the page and click "save change".
# Downloading a Remote Repository
## Overview of Git at the Command Line
Open up the command line, and check to see which version of Git
you have installed. Look at Git's short help, list of all
commands, and a single command. Recommend Stack Overflow /
Google in additional to the command line help.
### Lesson Objectives
By the end of this lesson, you will be able to retrieve help for git's
commands from the command line.
### Self-Check
You are able to check which version of git is installed from the command
line.
### Summary
The commands we used in this lesson allowed us to read the manual
pages for git from the command line.
- `git`
- `git help` (same as running git without a parameter)
- `git help clone`
For additional information on the specifics of using any one
command, do a Google search. You'll probably end up at Stack
Overflow. I've also put together a [comprehensive list of resources
for learning git](http://gitforteams.com/resources/offsite.html).
## Cloning your GitLab repository
With your fork of a projec setup, it's now time to download the
project so that you can work on it locally. There isn't actually a
fork command in git! When you create a fork of a project, you are
merely cloning, or copying, the repository to a new location. Once
you have a local clone of your repository, you will have essentially
setup a chain between the three repositories. The original
repository (my copy) is the "upstream project". It might receive
contributions from any number of people, but they will always need
to be approved by me. The next repository in your chain, is the
repository which you forked from my project. This one you have
write access to. Perhaps other people will be interested in the
adaptations you've been making to your copy, and will be interested
in helping you with yours (this is where the concept of "fork" comes
in, as the two repositories may diverge over time, just like the
tines on a fork). The third, and final repository in the chain, is
your local repository. From this repository you have one connection
to the remote repository you cloned from. You could add others as
well. In subsequent lessons we'll talk about why you might want to
do this.
Cloning a project is very straight forward. You will need to:
1. Navigate to the project page for the repository you want to clone.
2. Locate the instructions on how to clone, copy the instructions.
3. At the command line, navigate to the directory where you want to
download the repository to.
4. Paste the command line instructions.
Generally these instructions will be in the format of:
`git clone http://urltoproject/repository-name.git`
optionally, you may include a new directory name (by default the
name of the project is used as the directory name).
`git clone http://urltoproject/repository-name.git new-directory-name`
### Lesson Objectives
By the end of this lesson, you will be able to clone a repository
from a code hosting system, such as GitLab.
### Self-Check
Do you have a copy of the project on your hard drive? Navigate into
the directory and make sure there are files present. There will also
be a hidden folder, `.git`.
### Summary
The commands we used in this lesson allowed us to create a local
copy of our GitLab project.
`git clone http://urltoproject/repository-name.git new-directory-name`
We can repeat this command as many times as you like, to download
the repository multiple times (this can be helpful if you want to
throw away your local copy and start again from scratch).
## Reviewing History with git log
We'll be working a lot more with Git's log command in the lesson on
finding and fixing bugs. For now, let's use it to get a real quick
overview of the repository we've just downloaded. We can use Git in
two or three different ways, depending on what's compiled into our
system. We'll look at the full commit messages, a short log, and (if
you have it installed) Git's graphical browser. We'll also take a
quick look at how this compares to how GitLab displays the
information.
### Lesson Objectives
By the end of this lesson, you will be able to review the history
for a local repository using the log command.
### Self-Check
Are you able to find the two most recent commit messages for the
downloaded repository? What was a quick summary of the changes made?
Who were they made by?
### Summary
In order to review the history of our repository, we need to use the
log command. There are a number of parameters we can use to show
slightly different information.
- `git log`
- `git log --oneline`
Finally, the last little tool I find helpful, is some kind of
graph generator for my repository's history. This tool gives me
the context of where a change came "from" (are you a branch? is
it ahead of another branch in terms of commits?). GUIs for git
will give you a much more elegant view of your repository than
these tools, but they work just fine for me.
I can either draw the graph at the command line:
`git log --oneline --graph`
An example of this output would be as follows:
```
* edcd486 Updated deps.
* 05af892 No need for layout anymore.
* eb85b12 Merge pull request #11 from stevector/master--implements-spelling
|\
| * 086b01e Spelling fix in 2013-02-04-highlight.md
* | c5f46bd Merge pull request #10 from stevector/master--fixing-typo-in-readme
|\ \
| * | 58e67f4 Spelling fix in README
|/ /
* | eebb37d Merge pull request #8 from kenjis/fix_url
```
The dots represent a commit. Anything to the right of the first
is (or was) a branch. The branch names are not listed in this
output.
Or, I can open up the git browser, gitk, and click around a bit. The
git browser is a special add-on which might not be enabled in
your version of git. For example: this functionality is *not*
available in the OSX-installed version of git, but it is
available in the brew-installed version. To open the browser,
use the following command:
`gitk`
# Configuring Git
Over time, you will find little shortcuts that help you use Git at
the command line. Personally I've found those who are the most
frustrated with it, are the ones with the least amount of
customization. You don't *need* do to any of the things I've setup
in this lesson, but you might find them a little helpful. As this
setup will be hugely dependent on how you are working at the command
line, I'm not going to spend a lot of time in the *video* showing
you how to get this setup. There are some resources in the
repository that you've already downloaded (look for the "sample"
files in the directory `resources`).
There are two types of configuration settings you'll be making when
working with Git: global settings which apply to all repositories
that you work on, and local settings which only apply to the current
repository. An example of a global setting might be your name;
whereas your email might be customized based on personal projects
and work projects.
Global settings are stored in in the file `~/.gitconfig`, local
settings are stored in the file `.git/config` for the specific
repository you are working in. You will always be able to go back
and edit your settings if you want to.
## Identifying Yourself
In order to get credit for your work, you'll need to tell Git who
you are. We'll store this setting globally. As it's a global
setting, you don't need to be in a specific repository to make the
change.
### Lesson Objectives
By the end of this lesson, you will be able to add your name and
email to Git for proper attribution in commit messages.
### Self-Check
When you run the following command, is your name displayed?
`git config --get user.name`
### Summary
`git config --global user.name 'Your Name'`
`git config --global user.email 'me@example.com'`
If you want to make these changes only to the current repository,
replace the parameter `--global` with `--local`.
## Changing the Commit Message Editor
By default, you'll be using Vim. I really like Vim, so that's what
you'll be seeing in the videos. It's a bit hardcore though, so you
might want to change your editor to something else. Note: the commit
will only finish when you QUIT the editor, so you'll want to use
something fairly lightweight.
### Lesson Objectives
By the end of this lesson, you will be able to change the default
text editor for commit messages.
### Self-Check
When you run the following command, is the name of your text editor
displayed?
`git config --get core.editor`
### Summary
To change the text editor for your commit messages, use one of the
following commands as is appropriate for your editor of choice:
`git config --global core.editor mate -w`
`git config --global core.editor subl -n -w`
## Adding Color
Reading huge walls of text can be difficult. We'll add some color
helpers to our command line to make it easier to see what git is
doing.
### Lesson Objectives
By the end of this lesson, you will be able to enable the color
hinting to show branch colors, and diffs by color.
### Self-Check
Within the repository you downloaded for the previous lesson, when
you view the log, are the commit hashes a different color than the
author, date, and commit messages?
`git log`
### Summary
`git config --global color.ui true`
### Lesson Bonus: Customize Your Command Prompt
If you're working from the command line, you get ZERO clues
about what's going on with your files, until you explicitly ask
Git about them. This is tedious to keep having to ask. It's
like when you were 8 and sat in the back of the car whining at
the driver saying, "are we almost there yet?"
Instead of having to explicitly ask, I've modified my command line
prompt to tell me which branch I currently have checked out and
whether or not I've made changes to any of the files in my
repository. This is a fairly common hack, but every developer
will have their own little quirks on how they implement it.
Searching the web for `bash prompt git status` will yield lots
of results. My own prompt is fairly simple, but others have
added a lot more details to their prompt. For example: [Show your git status and branch (in color) at the command prompt](https://coderwall.com/p/pn8f0g) or [local
file status](https://github.com/magicmonty/bash-git-prompt). As
with all things technical: the more you add initially, the more
you'll need to debug if it doesn't work right away.
I found the fancy prompts to actually be quite fussy to set up,
and ended up giving up on the really detailed ones. I recommend
you too start with something really simple and then add to it if
you *really* need more information. The simple change in
colour, along with the name of the branch, actually suits me
just fine and is less distracting without all the extra
information.
This as a self-study piece.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment