Your quick-and-dirty guide to using Git!

# Prequisites

* Install Git - follow instructions [here](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) (and, actually, you will find that the docs [here](https://git-scm.com/doc) are pretty damn good, though perhaps a bit high-level for your first couple of days)
* Figure out how to open a command-line on your computer. On a Mac, Terminal comes pre-installed (though [iTerm](https://www.iterm2.com/) has a bunch of nice bells-and-whistles). On a Windows computer, press Windows+R, type "cmd", and press enter.
* Get used to navigating around your filesystem in your terminal. In examples below, I list the Mac command, then a slash, then the equivalent Windows command
 * `cd <directory>`/`chdir <directory>` changes your current directory to the target. On both systems, entering `..` (two periods) for the directory will change into the parent directory
 * `ls`/`dir` prints out the contents of the current directory
 * `pwd`/`cd` prints your current directory (if you get lost!)
 * `mkdir <directory>`/`mkdir <directory>` (yep, it's the same in both!) makes a new directory called `<directory>` inside your current one

# Basic Concepts

Git is a version control system. It allows you to track the state of a directory over its history, at checkpointed states called "commits". A commit is referred to by a SHA - a string of hexadecimal digits (0-9, a-f). A commit captures a point in time by capturing a "diff" (a change or set of changes to your directory) and the chain of commits that precede that particular one. Git figures out what state your directory should be in by applying diffs one after the other.

# Let's get started

Let's dive right in! I'll go back and explain what we did afterwards.

In the examples below, `$ <cmd>` means "enter `<cmd>` at a command line, then press enter". Anything not preceded by a `$` is output that you should expect from your terminal - your output might look slightly different from mine (especially the SHAs, the long strings of hexadecimal numbers), but hopefully mostly the same. Anything preceded by `#` is a comment - I'm explaining something directly to you, but it's not something that you should enter

Open your terminal, make a new directory called `git-experimentation`, move into it, then run `$ git init myFirstGitRepo`. If you get an error like `"command not found"` here, make sure you followed the git installation instructions correctly. You should get output like `Initialized empty Git repository in /Users/jackjack/git-experimentation/myFirstGitRepo/.git/` - the path here will look different for you, depending on where you created the directory.

In your favourite text editor (if you don't have one, [Sublime](https://www.sublimetext.com/) is a good choice for Mac, [Notepad++](https://notepad-plus-plus.org/) for Windows), create a file called `README.md` in that directory (`/whatever/whatever/git-experimentation/myFirstGitRepo/` - *not* in `.../.git`). Enter some text, and save the file.

In your terminal, go back to the `myFirstGitRepo` directory, and run:

```
$ git status
On branch master

No commits yet

Untracked files:
    README.md

nothing added to commit but untracked files present
$ git add README.md
$ git status
On branch master

No commits yet

Changes to be committed:
    new file:   README.md
$ git commit -m "My first commit"
[master (root-commit) 50a7ca1] My first commit
 1 file changed, 2 insertions(+)
 create mode 100644 README.md
```

Go back to your text editor, change the file, save it, then go back to your terminal and run:

```
$ git status
On branch master
Changes not staged for commit:
    modified:   README.md

no changes added to commit
$ git diff
# This output depends on what your change was, so I can't really predict it!
$ git add -A
$ git commit -m "My second commit"
[master 1bfe610] My Second Commit
 1 file changed, 1 insertion(+)
$ git log # Note that your output here will look *very* different from mine - especially the hex-strings - but hopefully the format should be the same!
commit 1bfe61037a983aaf89b0128c96d0f4537de5b63f (HEAD -> master)
Author: Jack Jackson <scubbojj@gmail.com>
Date:   Tue Apr 16 19:15:11 2019 -0700

    My Second Commit

commit 50a7ca1340321d7469b7eed96438d5153a6e3d96
Author: Jack Jackson <scubbojj@gmail.com>
Date:   Tue Apr 16 19:10:33 2019 -0700

    My first commit

$ git show 1bfe61 # Note that this is just the first few characters of the SHA for "My Second Commit" - so long as a SHA can be unambiguously identified by a prefix string (i.e. no other SHA exists in the history with that prefix), you can truncate references to it
commit 1bfe61037a983aaf89b0128c96d0f4537de5b63f (HEAD -> master)
Author: Jack Jackson <scubbojj@gmail.com>
Date:   Tue Apr 16 19:15:11 2019 -0700

    My Second Commit

diff --git a/README.md b/README.md
index d54ca78..fee0653 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,3 @@
# This content will, as above, be different based on what you edited
$ git checkout 50a7ca
```

Go back to your text editor (you may need to force it to refresh the file), and observe that it's been reverted back to the first "version"!

Before I explain those commands, we need to introduce some more concepts.

# Further concepts

Changes in git exist in exactly-one of three states:

* The "working tree". This is Git's name for "your filesystem (unmanaged by Git)". So, when you have edited a file in your text editor and saved it (but not run any further Git commands), the change is "in the working tree"
* The "index". This is where changes are "staged" for commit. They are ready to be committed, but not yet committed. `git add <filename>` adds the changes to `<filename>` to the index - `git add -A` adds all changes to all files in the directory to the index.
* A commit. Once you've staged all the changes that you want to put into a commit, `git commit -m "<message>"` make a commit. The commit will capture all the changes (the "diffs") that you added to the index, and create a new commit (with commit message `<message>`) which has the previous commit as the parent.

# So what did we do?

## git init <repoName>

This creates a git "repo" (repository) with the name that you specified - in this case, `myFirstGitRepo`. This creates a directory named `<repoName>`, a directory within it called `.git` (you probably won't see this with a usual `ls`/`dir` - you can see it with `ls -a`/`dir /A`, but you should be able to `cd`/`chdir` into it as usual) which contains a bunch of metadata about the repo

## git status

This tells you the status of your repo at that point in time. The first time you run `git status`, you could see that:
* you were on branch `master` (ignore that for now)
* you had made no commits yet (as expected)
* you had an untracked file named `README.md` ("untracked" because you have not yet staged/committed anything to do with that file, so Git "doesn't know anything about it")

## git add README.md

Staging the change to `README.md` - adding it to the index

## git status

Now you can see that you have a change staged, and "ready to be committed"

## git commit -m "First commit"

Congratulations! You made your first commit!

The `-m "<message>"` argument says 'make "`<message>"`' the message for this commit. I encourage this when you're starting out because, without that option, git will open up whatever your terminal's text editor is (usually, by default, vim, which is [famously confusing if you're not used to it](https://stackoverflow.blog/2017/05/23/stack-overflow-helping-one-million-developers-exit-vim/)), and ain't nobody got time for that :)

## git status

After having made some more changes to the file, `git status` shows you that you have changes not yet staged (note that it "knows about" `README.md`, so it's no longer an untracked file)

## git diff

This is a new command to you - `git diff` shows you "changes between your working tree and the index". This is *basically* equivalent to "changes that are not yet staged - that have not had `git add` run on them"

`git diff --cached <commit>` shows you "changes between the index and the named commit". If you omit the named commit, the current commit is used by default (this is usual for any command that accepts a commit as an argument). This is *basically* the same as "If I run `git commit`, what will get committed?"

## git add -A

This is a shortcut for "run `git add` for all files that this repo tracks (i.e. all files that it has ever tracked changes to)"

## git commit -m "My second commit"

As before - this creates a commit based on the changes that you've staged with `git add`

## git log

This shows information about your git history. Because you have two commits, this has two entries. Each entry shows:
* The commit's SHA
* The author and date of the commit
* The commit message

There are ton of different options you can pass to `git log` to change display options - some of my favourites are:
* `git log --format=format:'%C(yellow)%h%Creset %Cred%an%Creset %s' -5` - shows the 5 most recent commits in super-short form - short commit SHA, author, and first line of commit message
* `git log --graph --pretty=format:'%Cred%h%Creset - %s %C(bold blue)<%an>%Creset %Cgreen(%cr) %C(yellow)%d%Creset' --abbrev-commit --date=relative --branches` - similar format to above, but shows branches in history. Not so relevant to you right now, but will be useful when you get into branches!

## git show <SHA>

Shows information about a SHA. This shows the same information as in `git log`, followed by the diffs that were part of the commit.

## git checkout <SHA>

This resets your repo to match the state at the commit named `<SHA>`. In your case, you checked-out your first commit, which reset your `README.md` to its first-committed state.

If you only want to change a single file to its state at a previous commit, you can do `git checkout <SHA> -- <filepath>`.

# What's next? Github!

Those are the basics! You can stage up changes with `git add`, commit them with `git commit`, inspect your history with `git log` and particular points in history with `git show`, and reset to points in history with `git checkout <SHA>` or `git checkout <SHA> -- <filepath>`

There's a *lot* more you can do with Git, but that is enough to get you confidently able to make changes and know that you can unwind them if needs be.

I'll flesh this out later on (there is probably some setup that I'm missing, particularly around authentication and ssh keys), but the basic steps are:

* Go to https://github.com/ (creating an account, if you don't have one already)
* Create a new repo named `myFirstGitRepo`, skipping the "Initialize this repository with a README" step
* Follow the "push an existing repository from the command line" commands:
 * `git remote add origin git@github.com:<username>/myFirstGitRepo.git`
 * `git push -u origin master`

`git push` is the command that says "take my local commits, and update another repo with them" - in this case, the "other repo" is the one that GitHub hosts.

If you then refresh the repo page, you should see your README.md file displayed!