Agenda :

1. Version control intro and setup

2. An introduction version control : GIT
3. First steps with git: clone, add, commit, push
4. Introduction to undoing things in git
5. How to find and navigate a repo on the GitHub website
6. How to fork a repo in GitHub
7. Submit a pull request on the GitHub website
===================================================================================
1) Version control intro and setup

Step 1. Setup Git and Bash

Windows instructions
Install Bash on your computer. Please note that Windows command
prompt is not the same as Bash - we suggest that Windows users install Git for
Windows, which also installs Bash

download :
git-sct.com/download
update git if already installed
git update-git-for-windows
check version
git version

Mac or Linux instructions

Bash is available by default for these *nix based systems
Install Git on your computer.

Step 2. Sign up for GitHub

Create a GitHub account
If you do not already have a GitHub account, go to GitHub and
sign up fora free account. Pick a username that you like! This username is what
your colleagues will see as you work with them in GitHub and Git.

Take a minute to setup your account. If you want to make your

account more recognizable, be sure to add a profile picture to your account!

If you already have a GitHub account, verify that you can sign
in.

Step 3. Configure Git on your computer

Be sure to set up your username and e-mail from the command line.

$ git config --global user.name "Your Name"

$ git config --global user.email "your-email-used-for-github-
acct@email.com"
$ git config --global color.ui "auto"

If you’re not sure whether you’ve already configured Git, you can list
your configuration by executing git config --list.

get cofiguration
git config --global --list

===================================================================================
2) An introduction version control : GIT
What is Version Control?
A version control system maintains a record of changes to code and
other content. It also allows us to revert changes to a previous point in time.
 Types of Version control
There are many forms of version control. Some not as good:

Save a document with a new date (we’ve all done it, but it isn’t
efficient)
Google Docs “history” function (not bad for some documents, but limited
in scope).

Some better:
Git
Mercurial
Subversion

Why Version Control is Important

Version control facilitates two important aspects of many scientific
workflows:

1. The ability to save and review or revert to previous versions.

2. The ability to collaborate on a single project.

This means that you don’t have to worry about a collaborator (or your
future self) overwriting something important. It also allows two people working on
the same document to efficiently combine ideas and changes.

How Version Control Systems Works

Simple Version Control Model
A version control system tracks what has changed in one or more
files over time.
Version control systems begin with a base version of a document.
They then save the committed changes that you make.
You can think of version control as a tape: if you rewind the
tape and start at the base document, then you can play back each change and end up
with your latest version.

open : fig_1.png

Once you think of changes as separate from the document itself,

you can then think about “playing back” different sets of changes onto the base
document. You can then retrieve, or revert to, different versions of the document.

open : fig_2.png

Collaboration with version control allows to users to make

independent changes to the same document.

If there aren’t conflicts between the users’ changes (a conflict

is an area where both users modified the same part of the same document in
different ways) you can review two sets of changes on the same base document.

open : fig_3.png

A version control system is a tool that keeps track of these

changes for us.
Each version of a file can be viewed and reverted to at any time.
That way if you add something that you end up not liking or
delete something that you need, you can simply go back to a previous version.

Git & GitHub - A Distributed Version Control Model

 Git uses a distributed version control model.
This means that there can be many copies (or forks/branches in
GitHub world) of the repository.
When working locally, git is the program that you will use to
keep track of changes to your repository.
GitHub is a location on the internet (a cloud web server) that
acts as a remote location for your repository.
GitHub provides a backup of your work, that can be retrieved if
your local copy is lost (e.g., if your computer falls off a pier).

GitHub also allows you to share your work and collaborate with
others on projects.

open : fig_4.png

===================================================================================
3) First steps with git: clone, add, commit, push
Create a new repository on GitHub
1. To begin, sign in to your user account on GitHub.
2. In the upper right corner, click the + sign icon, then choose New
repository. This will take you to a page where you can enter a repository name
(this tutorial uses test-repo as the repository name), description, and choose to
initialize with a README (a good idea!).
3. It is a good idea to add a .gitignore file by selecting one of the
languages from the drop down menu, though for this tutorial it will not be
necessary.
4. Similarly, in practice you should choose a license to that people
know whether and how they can use your code.
5. Once you have entered a repository name and made your selection,
select Create repository, and you will be taken to your new repository web page.

Git at the command line

Below you will learn a series of commands that you can run at the
command line in git bash, terminal of whatever bash tool you are using. There are 2
types of commands that you will use

Bash commands: These are commands that are native to bash /

shell. They allow you to navigate around your computer, explore directory
structures, create and manipulate files and directories, and more. (e.g. ls, cd,
mkdir, etc)

Git commands: These are commands that are specific to git and
will only be available if you have git installed on your computer. Git specific
commands will always started with a call to git (e.g. git status, git clone, etc)

Clone your repository to your local machine

Next, clone your newly created repository from GitHub to your local
computer. From your repository page on GitHub, click the green button labeled Clone
or download, and in the “Clone with HTTPs” section, copy the URL for your
repository.

Next, on your local machine, open your bash shell and change your
current working directory to the location where you would like to clone your
repository. Note that here we are using a bash command - cd (change directory).

For example, on a Unix based system, if you wanted to have your

repository in your Documents folder, you change directories as follows:

cd Documents
 Once you have navigated to the directory where you want to put your
repository, you can use:

git clone https://github.com/URL-TO-REPO-HERE

The git clone command copies your repository from GitHub to your local
computer. Note that this is a git specific command.

git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY

When you run git clone repo-path-here, You should see output like:

Cloning into 'test-repo'...

remote: Counting objects: 5, done.
remote: Compressing objects: 100% (4/4), done.
remote: Total 5 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (5/5), done.
Checking connectivity... done.

Note: The repository name and output numbers that you see on your
computer, representing the total file size, etc, may differ from the example
provided above.

To verify that your repository now exists locally, type ls in your

terminal. The ls command lists the files & folders available in your current
directory. You should see a directory with the same name as the repository that you
created previously on GitHub.

Tracking changes with git add and git commit

Next use cd to change directories using the syntax:

cd my-repo-name

Replace my-repo-name with the folder name of your repo

cd folder_name

If you list all the files in this directory (using ls -a), you should
see all of the files that exist in your GitHub repository:

ls -a // dir

.git .gitignore LICENSE README.md

Alternatively, we can view the local repository in the finder (Mac), a

Windows Explorer (Windows) window, or GUI file browser (Linux).

Simply open your file browser and navigate to the new local repo.

Important Tip The .git element is listed when you use the ls -a
command shows up is actually a directory which will keep track of your changes (the
commits that you make) in git. Warning: Do not edit the files in this directory
manually!

Using either method, we can see that the file structure of our cloned
repo mirrors the file structure of our forked GitHub repo.
 Edit a file in your repo

Next, open up your favorite text editor and make a few edits to the
README.md file. Save your changes.

Once you are happy with your changes and have saved them, go back to
your terminal window and type git status and hit return to execute the command.

git status

On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
(use "git add <file>..." to update what will be
committed)
(use "git checkout -- <file>..." to discard changes in
working directory)

modified: README.md

no changes added to commit (use "git add" and/or "git

commit -a")

The output from git status indicates that you have modified the file
README.md. To keep track of this change to this file, you need to

1. add the changes, then

2. commit the changes.

Add and commit changes

You will use the add and commit functions to add and commit changes
that you make to git.

git add: takes a modified file in your working directory and places the
modified version in a staging area.

git commit takes everything from the staging area and makes a permanent
snapshot of the current state of your repository that is associated with a unique
identifier.

These two commands make up the bulk of many workflows that use git for
version control.

open : fig_5.png

Add files
You can add an individual file or groups of files to git tracking. To
add a single file, use

git add file-name-here-with-extension

To add the README.md file that you just modified, you’d use:

git add README.md

To add ALL of the files that you have edited at the same time, you can
use:

git add .
 git add --all

Use git add --all with caution. You do not want to accidentally add
things like credential files, .DS_Store files, or history files.

Commit files
Once you are ready to make a snapshot of the current state of your
repository, you can use git commit. The git commit command requires a commit
message that describes the snapshot / changes that you made in that commit.

A commit message should outline what changed and why. These messages
help collaborators and your future self understand what was changed and
why
allow you and your collaborators to find (and undo if necessary)
changes that were previously made.

If you are not committing a lot of changes, you can create a short one
line commit message using the -m flag:

git commit -m "Editing the README to try out git add/commit"

Alternatively, if you are committing many changes, or a small number of

changes that require explanation, you’ll want to write a detailed multi-line commit
message using a text editor.

If you have configured git to use your favorite text editor (via git
config --global core.editor your-fav-editor-here), then you can open that editor to
write your commit message using the git commit command:

git commit

Once you save your commit message and exit the text editor, the file
that you created will contain your commit message.

try : git log

Push changes to GitHub

So far we have only modified our local copy of the repository. To add
the changes to your git repo files on your computer to the version of your
repository on GitHub, you need to push them GitHub.

You can push your changes to GitHub with:

git push

You will then be prompted for your GitHub user name and password. After
you’ve pushed your commits, visit your repository on GitHub and notice that your
changes are reflected there, and also that you have access to the full commit
history for your repository!

===================================================================================
4) Introduction to undoing things in git
How to undo changes:
- before they’ve been staged (you haven’t used git add yet to add or
stage them),
- after they’ve been staged with git add, and
- after they’ve been committed to git.
 Undoing unstaged changes
If a file has been changed, but these changes have not yet been staged
with git add, then the changes can be undone using git checkout. The instructions
for using git checkout to undo changes are described in the output of git status.

Let’s look at an example. First, let’s modify the readme file by adding
some text to it at the command line.

# append "Some random text" to the README file in shell

echo 'Some random text' >> README.md

Next, type git status to see how that change impacted git

$ git status

In the example above, git status was run in the command line after a
file was edited. When you run git status, git will first provide the following
output:

On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working
directory)

modified: README.md

no changes added to commit (use "git add" and/or "git commit -a")

The output from git status tells you that you can use git checkout --
<file> to discard changes to that file in your repo. So, if you don’t like the
changes made to the README.md file, you can revert back to the last committed
version using:

git checkout -- README.md

git status

Which returns:

On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean

Now, the contents of your README.md file has been reverted to the last
saved or committed version and you’ve discarded the most recent changes.

open : fig_6.png

Unstaging staged changes

Remember that once you add a set of changes to git using git add, the
file is then staged. If a file has been changed and then staged via git add, then
you use git reset to pull the most recently committed version of the file and undo
the changes that you’ve made.

Fortunately, the output of git status gives us a hint for how to undo
our staged changes:
 # modify the README file
echo 'Some more changes' >> README.md

git add README.md

git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes to be committed:
(use "git reset HEAD <file>..." to unstage)

modified: README.md

You use git reset HEAD <file> to unstage our changes. HEAD refers to
the most recently committed version of the file:

git reset HEAD README.md

Unstaged changes after reset:

M README.md

Data tip: HEAD refers to the most recent version of your file. You can
also revert to an older version using HEAD~1, HEAD~2 etc.

When you use git reset, your changes still exist in the file, but the
file has been unstaged (the changes are not added to git, yet).

git status

On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working
directory)

modified: README.md

no changes added to commit (use "git add" and/or "git commit -a")

Now that you have changes that are not staged, you can use git checkout
to undo those modifications. Git reset is essentially the opposite of the command
git add. It undoes the add.

** Undoing a commit **
If you have modified, added and committed changes to a file, and want
to undo those changes, then you can again use git reset HEAD~ to undo your commit.
Similar to the previous example, when you use git reset the modifications will be
unstaged.

# create a sensitive file

echo '123-45-6789' >> social-security.txt

# add it
git add --all

# commit
git commit -m 'Accidentally including my social security number
in my file'
 git status
On branch master
Your branch is ahead of 'origin/master' by 1 commit.
(use "git push" to publish your local commits)
nothing to commit, working directory clean

Now you can undo this commit with git reset HEAD~:

git reset HEAD~

git status
On branch master
Your branch is up-to-date with 'origin/master'.
Untracked files:
(use "git add <file>..." to include in what will be committed)

social-security.txt

nothing added to commit but untracked files present (use

"git add" to track)

Notice that now your file is no longer being tracked!

If you inspect the output of git log, you will notice that your
previous commit is no longer part of the repository’s history.

** Ignore sensitive files **

If you do have sensitive files in a repository that you never want to
track with git, you can add those file names to a file called .gitignore, and git
will not track them. For instance, if you have a text file that contains sensitive
information such as a social security number called: social-secutity.txt that you
don’t want to keep track of, you can add that file to a .gitignore file.

The .gitignore file lives in the home directory of your repo.

# create a .gitignore file - only do this if one doesn't already exist

touch .gitignore

Now open the that file in a text editor and add the following lines
below:

# contents of the .gitignore file

social-security.txt

Any files listed in this file will be ignored by git. You can also tell
git to ignore entire directories.
===================================================================================
=
5) How to find and navigate a repo on the GitHub website

Navigate GitHub
Repositories (AKA repos)
According to the GitHub glossary:

A repository is the most basic element of GitHub. They’re easiest

to imagine as a project’s folder. A repository contains all of the project files
(including documentation), and stores each file’s revision history. Repositories
can have multiple collaborators and can be either public or private.
 In this workshop you will collaborate with your colleagues using the
SLK-SDET repo.

Find an existing repo

The first thing that you’ll need to do is find the username/SLK-SDET.
You can find repos in two ways:

Type “SLK-SDET” in the github.com search bar to find the repository.

Use the repository URL if you have it: https://github.com/username/SLK-SDET.

The GitHub interface

Once you have found the https://github.com/username/SLK-SDET repo,
explore it.

Notice the format of the repository name. Repository names will always
begin with the account or organization name followed by the repo name, like this:
organization-or-account-name/repo-name

The full name of our repo is:

username/SLK-SDET

Next, below the repo full name, explore the header tabs
Notice the following headers that you will use in this workshop:

- Code: Click here to view structure & contents of the repo.

Issues: Submit discussion topics, or problems that you are having with
the - content in the repo, here.
- Pull Requests: Submit changes to the repo for review / acceptance.

===================================================================================
6) How to fork a repo in GitHub

What is a fork?
A GitHub fork is a copy of a repository (repo) that sits in your
account rather than the account from which you forked the data from. Once you have
forked a repo, you own your forked copy. This means that you can edit the contents
of your forked repository without impacting the parent repo.

When you fork a repo, you make an exact copy of the repo in your own account.
Once you create a copy in your account you own it! Thus, you you can freely modify
it as you wish. Image source: Colin Williams, NEON

An example forking workflow

In this session you will work from a central repo owned by SLK-SDET.
You will:

- Fork this repo

- Clone the fork of your repo, so you can edit the contents locally
- Make edits to your local cloned copy of the repo on your computer
- add, commit and push those edits back to your fork on GitHub
- Suggest the changes that you made, to be added to the Earth Lab
central repo using a pull request

This workflow has a central repository - which is the one that SLK-SDET owns.
Everyone in the workshop will then contribute to the central repository. There are
other Git and GitHub workflows too. However in this workshop, we are demonstrating
a central repo workflow.
 open : fig_8.png

How to Fork a Repo

You can fork any repo by clicking the fork button in the upper right
hand corner of a repo page.

open : fig_9.png

Explore your SLK-SDET fork

Now, navigate to your new fork. Its name should be:

YOUR-USER-NAME/SLK-SDET.

Sometimes, navigating between repositories and keeping track of where

you are on the GitHub website can be confusing. In this case note the URL. The
Earth Lab central repo contains the earthlab account name:

https://github.com/username/SLK-SDET

and your forked repo contains your account name:

https://github.com/YOUR-USER-NAME/SLK-SDET

A good way to figure out which repo you are viewing is to look at the

The name of the repo: does it contain your username? Or your

colleagues?
Look at the path or URL to the repo and ask the same questions.

Your fork vs. the central repo

When you create a fork, it is an exact copy, or completely in sync
with, the parent repo. You could confirm this by comparing your fork to the Earth
Lab central repository using the pull request option. We will learn about pull
requests in the next lesson

The fork will remain in sync with the central repo until:

- You modify your forked copy of the repo.

- The central repository is modified.
If you modify your forked repo, the changes will not be reflected in the
central repo until you merge your fork with the central repo.
===================================================================================
7) Submit a pull request on the GitHub website

You have now learned how to:

- Fork a repo in someone else’s github account to your github account
- Clone this repo to your local computer
- Edit copies of that cloned repo locally on your computer
- add, commit those edits to your git repo locally
- Push the committed edits back to your fork

In this lesson, you’ll learn how to submit a pull request to suggest that
your edits are included in another (the central Earth Lab) repo.

open : fig_10.png

About pull requests

A pull request to another repo is similar to a “push”. However it
allows for a few things:

It allows you to contribute to another repo without needing

administrative privileges to make changes to the repo.

It allows others to review your changes and suggest corrections,

additions, edits, etc..

It allows repo administrators control over what gets added to their

project repo.

The ability to suggest changes to ANY repo, without needing

administrative privileges is a powerful feature of GitHub. In our case, you do not
have privileges to make changes to the username/SLK-SDET repo. However, you can
make as many changes as you want in your fork, and then suggest that username those
changes into their repo, using a pull request.

Pull requests in GitHub

Pull requests are the heart of collaboration on GitHub. When you open a
pull request, you’re proposing your changes and requesting that someone review and
pull in your contribution and merge them into their project.

Pull requests show diffs, (differences), of the content between your

repo and the repo that you are submitting changes to. The changes, additions, and
subtractions are shown in green and red.