================================================================
  GIT - NOTES
  A one-page reference from the workshop.
  Keep it. Add to it. It is only a text file.
================================================================

Nothing in here is something you have to memorise. You will
remember the six commands you use every day, and look up the
rest forever. That is what everybody does.


----------------------------------------------------------------
  WHAT IT IS FOR
----------------------------------------------------------------

  Snapshots      a record of your code at a point in time
  Parallel work  several people, different parts, at once
  Rewind         go back to any snapshot, whenever you like

A commit is a save point.
A branch is a parallel save file.

Everything else is detail.


----------------------------------------------------------------
  GIT IS NOT GITHUB
----------------------------------------------------------------

Git is the tool on your machine. GitHub, GitLab and Bitbucket
are places to keep a copy and work with other people.

You can use Git with none of them. You cannot use any of them
without Git.


----------------------------------------------------------------
  THE FOUR PLACES YOUR CODE LIVES
----------------------------------------------------------------

  WORKING TREE      the files you are editing right now
  STAGING AREA      what will go into your next commit
  LOCAL REPOSITORY  .git - your whole history, on your disk
  REMOTE            the shared copy, on GitHub or a server

And the commands that move code between them:

  git add       working tree  ->  staging area
  git reset     staging area  ->  working tree
  git commit    staging area  ->  local repository
  git push      local         ->  remote
  git fetch     remote        ->  local
  git pull      remote        ->  working tree

  git pull  =  git fetch  +  git merge

The staging area is the part that is genuinely unusual. It is
there so you can commit SOME of your changes and not others.


----------------------------------------------------------------
  STARTING OUT
----------------------------------------------------------------

  git init                    start a repository here
  git clone <url>             copy an existing one
  git status                  what is going on right now
  git log                     the history
  git log --oneline --graph   the history, readably

  git add <file>              stage one file
  git add .                   stage everything
  git commit -m 'message'     record what is staged

Type git status constantly. It is the cheapest command in Git
and it tells you what state you are in and usually what to do
next. It cannot break anything.


----------------------------------------------------------------
  BRANCHES
----------------------------------------------------------------

  git branch                    list branches
  git branch <name>             create one
  git checkout <name>           switch to one
  git checkout -b <name>        create and switch, in one go
  git branch -d <name>          delete one

A branch is not a copy of your files. It is a NAME pointing at
a commit. That is why making one is instant and free, and why
throwing one away costs you nothing.


----------------------------------------------------------------
  COMMITS WORTH READING
----------------------------------------------------------------

Make each commit ONE change, for ONE reason. The test: can you
describe it without using the word "and"?

Why it matters: you can undo one thing later without losing the
other four that were bundled in with it.

Write the message for the person reading it in six months. That
person is you, and you will not remember.

  Good     Add login form validation
  Good     Fix crash when config file is missing
  Bad      misc bugfixes
  Bad      more code
  Bad      aaaaaaaa


----------------------------------------------------------------
  MERGING
----------------------------------------------------------------

  git merge <branch>      merge that branch into this one
  git merge --abort       back out of a merge that went wrong
  git add <file>          mark a conflicted file as resolved
  git commit              finish the merge

git merge --abort loses nothing. It puts you back exactly where
you were before you started the merge. Say that out loud to a
panicking teammate.


----------------------------------------------------------------
  WHEN IT CONFLICTS
----------------------------------------------------------------

A conflict means Git could not choose for you. It is not an
error. It is a question.

Git puts both answers in the file and asks you to pick:

  <<<<<<< HEAD (current change)
      readFileAndGenerating(file, split);
  =======
      readFileAndGenerate(input, split);
  >>>>>>> main (incoming change)

Delete the markers. Keep the code you want - maybe one side,
maybe both, maybe neither and you write something new. Then:

  git add <file>          this one is sorted
  git commit              done

VS Code puts "Accept Current / Incoming / Both" buttons on top
of exactly these markers. The buttons only edit the text for
you; there is nothing magic underneath.


----------------------------------------------------------------
  UNDOING THINGS
----------------------------------------------------------------

First ask: where is the change right now?

  WORKSPACE    git restore <file>          throw the edits away
  STAGE        git restore --staged <file> unstage, keep the edits
  LOCAL REPO   git reset --soft HEAD~1     uncommit, keep the edits
  REMOTE       git revert <commit>         a new commit that undoes it

  git commit --amend      fix the last commit (message, or a file
                          you forgot to add)
  git stash               park your changes for later
  git stash pop           and get them back

Reset what only you have. Revert what everyone has. Reset and
amend rewrite history, so use them only before you push.

  git reset --hard        the one undo you cannot undo: uncommitted
                          changes are gone, Git never had a copy


----------------------------------------------------------------
  WORKFLOW - ON YOUR OWN
----------------------------------------------------------------

  1. git checkout main
     git pull

  2. git checkout -b feature/add-login

  3. git add .
     git commit -m "Add login form"

  4. git checkout main
     git merge feature/add-login

  5. git branch -d feature/add-login


----------------------------------------------------------------
  WORKFLOW - ON A TEAM, STARTING OUT
----------------------------------------------------------------

  1. git checkout main
     git pull

  2. git checkout -b feature/add-login

  3. git add .
     git commit -m "Add login form"

  4. git fetch origin              <- do this often
     git rebase origin/main

  5. git checkout main
     git merge --ff-only feature/add-login
     git push

  6. git branch -d feature/add-login

Step 4 is the new one. Pull main into your branch regularly and
the merge at the end is boring. Leave it a fortnight and it is
not.


----------------------------------------------------------------
  WORKFLOW - ON A TEAM, IN PRACTICE
----------------------------------------------------------------

  1. git checkout main
     git pull

  2. git checkout -b feature/add-login

  3. git add .
     git commit -m "Add login form"

  4. git push origin feature/add-login

  5. Open a pull request on GitHub or GitLab
       base: main   compare: feature/add-login
       give it a title, a description, and context

  6. Review and discuss
       comments, suggestions, testing
       push more commits - they join the PR automatically

  7. If main has moved since you branched:
       git fetch origin
       git merge origin/main
       git push

  8. Merge it
       Squash merge   -> one clean commit
       Rebase & merge -> linear history
       Normal merge   -> not recommended

  9. git branch -d feature/add-login
     git push origin --delete feature/add-login

The review in step 6 is the point of the whole workflow. The
commands are just how you get there.


----------------------------------------------------------------
  GETTING UNSTUCK
----------------------------------------------------------------

  git status              always start here
  git log --oneline       what has actually happened
  git merge --abort       undo a merge in progress
  git restore <file>      throw away changes to one file
  git help <command>      the full manual, q to quit

Almost nothing in Git is unrecoverable once it has been
committed. Committing early and often is what buys you that.


----------------------------------------------------------------
  WHERE TO GO NEXT
----------------------------------------------------------------

  learngitbranching.js.org   branches drawn as you type them
  ohmygit.org                an actual game about learning Git
  ohshitgit.com              how to undo the thing you just did
  w3schools.com/git          a click-through tutorial from zero
  git-scm.com/book           Pro Git - the reference, free

learngitbranching is the fastest way to make branching stop
feeling abstract. Half an hour there is worth a lot of reading.


================================================================
  Six commands cover most of what most people do most days.
  The rest you look up.
================================================================