Git the Docs: A fun, hands-on introduction to version control

BECKY TODD | LEAD CONTENT DESIGNER | @BECKATODD
Git the Docs
A fun, hands-on introduction to version control

Welcome!
We're here to help you learn how
to use Git.
@beckatodd | #WriteTheDocs

I am not a Git expert, but…!

https://bitbucket.org/beckytodd/learn-git-
wtd-aus-2019/src/master/resources/

1
2
3
Work ahead only if you dare...
Wait to run commands until instructed. Otherwise, you might get your working tree
into a wonky state.
Let us know if you get stuck.
Raise your hand if a command fails or if you get an unexpected result and don't know
how to fix it.
Ask questions.
Raise your hand if you have a question. We're here to help you learn.
Ground rules

Agenda
Tools
Git concepts
Basic Git workflow
Beyond the basics
Resources
Bonus: Merge conflicts

Tools
Hosting services, text editors, and the command line

Hosting services
Software products that store Git repos
on a server
Git
A software program installed on your
computer

GitHub
www.github.com
Hosting services
GitLab
https://about.gitlab.com/
Bitbucket
www.bitbucket.org

Git Bash
Comes with Git for Windows
Command line utilities
Command line
Default Windows CLI
Terminal
Default macOS CLI

Sublime Text Atom Visual Studio
Code
Vim
Cross-platform editors

Gitconcepts
Repos, workflows, and more

VERSION CONTROL
A system that
records changes
over time.

GIT REPOSITORY (REPO)
A container for
project files.

PULL REQUEST
A web interface
for reviewing,
approving, and
merging changes.

Upstream
Fork
Fork Fork

Basic workflow
1. create a branch
2. add our work (stage changes)
3. commit our work locally
4. push the branch to the remote repo (Bitbucket)
5. create a pull request (Bitbucket)
6. merge the changes into the master branch
7. pull changes from the remote repo

Basic workflow
1. create a branch
6. merge the changes into the master branch
2. add our work (stage changes)
5. create a pull request (Bitbucket)
3. commit our work locally
4. push the branch to the remote repo (Bitbucket)
7. pull changes from the remote repo

Basic Git workflow
Let’s "git" with it…

1. Get help

git -- help
Git’s documentation is
built in — try it for
yourself!
$ git --help
usage: git [--version] [--help] [-C <path>] [-c name=value]
[--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
[-p | --paginate | --no-pager] [--no-replace-objects] [--bare]
[--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
<command> [<args>]
These are common Git commands used in various situations:
start a working area (see also: git help tutorial)
clone Clone a repository into a new directory
init Create an empty Git repository or reinitialize an existing one
work on the current change (see also: git help everyday)
add Add file contents to the index
mv Move or rename a file, a directory, or a symlink
reset Reset current HEAD to the specified state
rm Remove files from the working tree and from the index
examine the history and state (see also: git help revisions)

2. Create a workspace

Workspace
setup
Make a folder named
repos in a root folder.
$ mkdir repos && cd repos
repos/ $
macOS
$ cd c:
$ mkdir repos && cd repos
/c/repos/ $
Windows

3. Fork the repo

https://bitbucket.org/beckytodd/learn-git-wtd-aus-2019/

https://bitbucket.org/angie-wallaby/learn-git-wtd-aus-2019/

4. Clone locally

• Clones a repository into a newly created directory
• Creates remote-tracking branches for each branch in the cloned repository
(visible using git branch -r),
• Creates and checks out an initial branch that is forked from the cloned
repository's currently active branch (typically master).
$ git clone <remote-info>

git clone
Clones your fork into
its own directory
inside repos/.
$ git clone git@bitbucket.org:angie-
wallaby/learn-git-wtd-aus-2019.git
Cloning into 'learn-git-wtd-aus-2019'...
Warning: Permanently added the RSA host key for IP address
'18.205.93.0' to the list of known hosts.
remote: Counting objects: 13, done.
remote: Compressing objects: 100% (9/9), done.
remote: Total 33 (delta 11), reused 0 (delta 0)
Receiving objects: 100% (13/13), 108.28 KiB | 1.14 MiBs,
done.
remote: Total 13 (delta 0), reuse 0 (delta0)

See what
happened
Switch to the learn-
git-wtd-aus-2019
directory, and list its
contents.
$ cd learn-git-wtd-aus-2019
exercise-one/ exercise-two/ LICENSE.txt resources/
$ ls
repos/learn-git-wtd-aus-2019/ $
$ open .
$ explorer .

5. Set up remotes

We'll use three different arguments for the git remote command:
• -v to see the URLs of all remotes
• add <name> <url> to link to a new remote (upstream)
• set-url --push <name> <url> to disable the ability to push to the
upstream remote
$ git remote [various args]

View remotes
Shows a list of
remotes associated
with your repo.
The -v argument
prints the URL after
the name.
$ git remote -v
origin git@bitbucket.org:angie-wallaby/learn-git-wtd-
aus-2019.git (fetch)
origin git@bitbucket.org:angie-wallaby/learn-git-wtd-
aus-2019.git (push)

Add
upstream
remote
Adds a connection to
the original repo,
which we're naming
upstream.
This command
requires the URL of
the main repo
(upstream).
$ git remote add upstream
git@bitbucket.org:beckytodd/learn-git-
wtd-aus-2019.git

View remotes
Shows a list of
remotes associated
with your repo.
The -v argument
the name.
$ git remote -v
origin git@bitbucket.org:beckytodd/becky-learn-git-wtd-
aus-2019.git (push)
upstream git@bitbucket.org:beckytodd/learn-git-wtd-
upstream git@bitbucket.org:beckytodd/learn-git-wtd-aus-
aus-2019.git (push)

Disable push
on upstream
remote
Updates the URL of
the remote named
upstream.
The --push argument
specifies that we
want to reset only the
URL associated with
the git push
command.
$ git remote set-url --push upstream
DISABLED

View remotes
Shows a list of
remotes associated
with your repo.
The -v argument
the name.
$ git remote -v
aus-2019.git (push)
upstream git@bitbucket.org:beckytodd/learn-git-wtd-
upstream DISABLED (push)

git fetch
Gets updates from the
upstream repository.
$ git fetch upstream
From bitbucket.org:beckytodd/learn-git-wtd-aus-2019
* [new branch] master -> upstream/master

Upstream (upstream)
Fork (origin)

Break time
(5 mins)

6. Branch

• Lists all branches (no args)
• <name> creates a new branch*
$ git branch [various args]

git branch
View all local
branches.
$ git branch
* master

Always commit or stash changes before changing branches.
• <branch-name> specify a branch name to switch it
• -b <branch-name> to create a new branch AND switch to it
• -b <branch-name> <remote>/<branch> to create a new branch from
a branch on a specified remote (like upstream/master) AND switch to it
$ git checkout [various args]
🎉

• Cannot contain spaces
• Are case sensitive
• Should be short and descriptive
• Follow company style (for example, include issue numbers)
Branch names

git checkout  
-b
Create and checkout a
new branch for your
work.
$ git checkout -b <name>-first-branch
upstream/master
Switched to a new branch 'angiew-first-branch'
Your branch is up to date with 'upstream/master'

7. Edit the docs

Edit your file
Open the file that has
your name on it, and
make a change or two.
../exercise-one/<file-name>.md
---
title: "About berries"
---
# About berries
Berries are small fruits. They come in all shapes and
sizes. Scientists define berries as "a fruit produced from
the ovary of a single flower in which the outer layer of
the ovary wall develops into an edible fleshy portion
(pericarp)."
There are a number of fruts that you wouldn't normally
think of as berries, such as:
- bananas

8. Add and commit

Shows the status of the working tree:
• changed files
• deleted files
• new files (untracked)
• renamed (moved) files
• which files are staged (added)
$ git status

git status
See the state of the
working tree.
$ git status
On branch angiew-first-branch
Changes not staged for commit:
(use "git add <file>..." to update what will be
committed)
(use "git checkout -- <file>..." to discard changes in
the working directory)
modified: exercise-one/<file-name>.md
no changes added to commit (use "git add"/or "git commit -
a")

• Adds the specified file(s) to staging
$ git add <file-name>

git add
Add your file to stage
your changes.
$ git add exercise-one/<file-name>.md
Changes to be committed:
(use "git reset HEAD <file>..." to unstage)
$ git status

git reset
Remove your file from
staging.
$ git reset exercise-one/<file-name>.md
Changes not staged for commit:
(use "git add <file>..." to update what will be
committed)
(use "git checkout -- <file>..." to discard changes in
the working directory)
no changes added to commit (use "git add"/or "git commit -
a")
$ git status

• Write a commit message in editor, like Vim (no args)
• -m "Some message" write a commit message inline
$ git commit [various args]

git commit
Use the -m argument
and add a commit
message in quotes.
$ git commit -m "Correcting spelling
errors and typos"
[angiew-first-branch 1ec8e60] Correcting spelling errors
and typos
1 file changed, 4 insertions(+), 4 deletions(-)

• Are associated with you
• Are kinda forever 💎
• Should be succinct and descriptive
• Follow company style (for example, include issue numbers)
• Line length limits may apply*
Commit messages

• See the Git history in the command line
$ git log

git log
See the git history in
the command line
interface.
$ git log
Commit d850bc4...(HEAD -> angiew-first-commit)
Author: Angie Wallaby <example-email@example.com>
Date: Wednesday November 13 12:03:58 2019 -0700
Correcting typos and spelling errors
Commit c845249... (upstream/master, origin/master, origin/
angiew-first-commit, origin/HEAD, master)
Merge: Becky Todd <btodd@atlassian.com>
Date: Wednesday November 13 13:01:14 2019 -0500
Merged wtd-class-set-up-merge-conflict into master
....

9. Push your work

• Pushes the current branch to origin (no args)*
• <remote> <branch> specifies the exact remote and branch
$ git push [various args]

git push
This command sends
a copy of all non-
pushed commits on
your branch to
Bitbucket.
$ git push origin <name>-first-branch
Enumerating objects: 7, done.
Counting objects: 100% (7.7), done.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 391 bytes | 0 bytes/s, done.
Total 4 (delta 3), reused 0 (delta 0)
remote:
remote: Create pull request for angiew-first-branch:
remote: https://bitbucket.org/angie-wallaby/learn-git-
wtd-aus-2019/pull-requests/new?source=angiew-first-
branch&t=1
remote:
To bitbucket.org:angie-wallaby/learn-git-wtd-aus-2019.git
* [new branch] angiew-first-branch -> angiew-first-branch

10. Create pull request

• Use a descriptive title.
• Describe the changes you in the pull request.
• Indicate what you want the reviewers to review (for example, Please check
grammar and technical accuracy).
• Select reviewers who are responsible for approving and merging changes.
Pull requests

Group activity:  
Create a pull request

11. Keep in sync

• Downloads objects from origin, without making local changes (no args)
• <remote> specifies the remote to download objects from
$ git fetch [various args]

git fetch
Gets updates from the
upstream repository
(including branches),
along with the objects
associated with the
updates.
Tip: git fetch does
not make local
changes.
$ git fetch upstream
remote: Counting objects: 9, done.
remote: Compressing objects: 100% (9/9), done.
remote: Total 9 (delta 5), reused 0 (delta 0)
Unpacking objects: 100% (9/9), done.
* [new branch] dev-branch -> upstream/dev-branch
* [new branch] master -> upstream/master

• Incorporates objects into the current branch from origin (no args)*
• <remote> <branch> specifies the remote and branch to incorporate
objects from
$ git pull [various args]

git checkout,
git pull
$ git checkout master
* branch master -> FETCH_HEAD
Updating 0d85853..435eeb2
Fast-forward
exercise-one/.DS_Store | Bin 6148 -> 0 bytes
exercise-one/<file-name>.md | 38 ++++++++++++++++++++++
++++++++++++++++
exercise-one/<other-file-name>.md | 38 ++++++++++++++++++++++
++++++++++++++++
merge-conflict/<another-file-name>.md | 7 -------
4 files changed, 76 insertions(+), 7 deletions(-)
delete mode 100644 exercise-one/.DS_Store
create mode 100644 exercise-one/<file-name>.md
create mode 100644 exercise-one/<other-file-name>.md
delete mode 100644 merge-conflict/<another-file-name>.md
$ git pull upstream master

git push
This command sends
a copy of all non-
pushed commits on
your version of the
master branch to
Bitbucket.
$ git push origin master
Enumerating objects: 7, done.
Counting objects: 100% (7/7), done.
Delta compression using up to 8 threads
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 406 bytes | 406.00 KiB/s, done.
Total 4 (delta 2), reused 0 (delta 0)
To bitbucket.org:beckytodd/becky-learn-git-wtd-aus-2019.git
0d85853..435eeb2 master -> master

Questions

Beyond basics
Best practices and additional Git commands

Best practices
Tips, tricks, and advice

DON'T BE AFRAID TO ADD,
COMMIT, AND PUSH OFTEN.

A well-cared for [Git] log is a
beautiful and useful thing.
Chris Beams, https://chris.beams.io/posts/git-commit/

Git commands
Going beyond the basic workflow

• Lists all branches (no args)
• <name> creates a new branch*
• -r shows you the remote associated with a branch
• -d or -D deletes the specified branch
$ git branch [various args]

Delete a
branch
$ git branch -d <name>-first-branch
Deleted branch angiew-first-branch was (d850bc4)

• Show changes for all files that are unstaged (no args)
• --cached shows changes for files that have been staged (diff between last
commit and the staged changes)
• <file-name> shows changes for a specific file
$ git diff [various args]

• Stashes all local changes (no args)
• list shows a list of all of your stashes and associated branches
• apply stash@{#} applies the changes saved in a specified stash to your
current branch
• drop stash@{#} drops the stash from Git
$ git stash [various args]

THERE'S SO MUCH MORE.
I'M STILL LEARNING GIT,
EVEN 7+ YEARS LATER...

Resources
Continue learning about Git and command line interfaces

Git skills and tools
Resources for further learning

Read the manual
https://git-scm.com/doc

Learn Git branching - pcottle
http://learngitbranching.js.org/

Git tutorials - Atlassian
https://www.atlassian.com/git/tutorials/learn-git-with-bitbucket-cloud

Sourcetree (tool)
https://confluence.atlassian.com/get-started-with-sourcetree/install-and-set-up-sourcetree-847359043.html

Command line skills
Resources for leveling up your command line knowledge

Learn the Command Line - Codecademy
https://www.codecademy.com/learn/learn-the-command-line

Open Vim (tutorial)
http://www.openvim.com/

Bonus: Merge conflicts

12. Resolve merge conflict

Thank you!
BECKY TODD | LEAD DEVELOPER CONTENT DESIGNER | @BECKATODD

Git the Docs: A fun, hands-on introduction to version control

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Git the Docs: A fun, hands-on introduction to version control

Similar to Git the Docs: A fun, hands-on introduction to version control (20)

Recently uploaded

Recently uploaded (20)

Git the Docs: A fun, hands-on introduction to version control