dotfiles/notes/shell/git_notes.md

## Quick start
Git is an indispensable tool for code development, though in reality you'll only
use a few commands on a day to day basis. This section provides a quick overview
of those commands
```
    $ git fetch
    $ git status -s
    $ git diff file_1
    $ git add some_dir
    $ git commit -m "Changed some directory"
    $ git switch -c new_branch
    $ git restore file_2
    $ git commit -a
    $ git log --graph --all --oneline --decorate | less
    $ git push
```
The above represent ~90% of git commands you'll use. For some of these, like the
`git log` command, you should setup aliases

#### Manual pages
    $ man gittutorial
    $ man giteveryday
Some useful manual pages for referencing non-specifics

    $ man git-rebase
    $ git help rebase
    $ tldr git rebase
For information on a single command, add a hyphen to separate out the
subcommand. If using `tldr` type the command as you normally would

#### Referencing commits
While most git commands default to `HEAD` without a commit passed, they often
accept other commits to operate on. Some commands also need another commit to
operate, like `git merge`

    $ git show HEAD      # References the current HEAD
    $ git show HEAD^     # References one commit above the HEAD
    $ git show HEAD^^    # Two commits above HEAD
    $ git show HEAD~4    # 4 commits above HEAD
    $ git show a22a398   # Commit starting with SHA1 a22a398
    $ git show v0.2.0    # Commit tagged with v0.2.0
    $ git show master    # Tip of the master branch
    $ git show origin/dev  # Tip of the local copy of the origin's dev branch
Various examples of referencing commits. These can be mixed together for more
complicated referencing, though that's not too common

    $ git show HEAD~4..     # All commits from 4 commits before to HEAD
    $ git show v2.0..HEAD^  # Commits from tag v2.0 to one before HEAD
Some commands accept ranges of references. As expected, if one end of the range
is missing, it'll use a default upper/lower bound

    $ git merge origin/master^
Merges one before the tip of the local copy of the origin's, possibly outdated,
master branch to the current branch. Very useful when working offline

## Project setup
#### New projects
    $ git init
Create a new git repository in the current directory with a master branch

    $ git remote add origin git@github.com:Aizuko/configs.git
    $ git remote add origin ssh://git@github.com:22/Aizuko/configs.git
Sets up a remote origin on GitHub. This example uses ssh to connect, though
often http will also be supported. The second example specifies port 22

    $ git push --set-upstream origin master
Pushes the master branch to the remote origin

#### Using a previous project
    $ git clone ssh://git@github.com/Aizuko/configs.git
    $ git clone https://github.com/Aizuko/configs.git
Clone a git repository from a remote. Everything will automatically be setup

    $ git clone -b dev --single-branch --depth=1 ssh://git@github.com:22/Aizuko/configs.git
Clone the tip of the dev branch. Useful for saving storage, if you only need the
latest commit

    .git/config
    [remote "origin"]
     - fetch = +refs/heads/dev:refs/remotes/origin/dev
     + fetch = +refs/heads/*:refs/remotes/origin/*
Sets git to synchronize all branches from origin, instead of just `dev`

    $ git remote -v
List the remotes for this repository. Often useful if you want to change the
connection protocol

    $ git remote set-url origin git@github.com:Aizuko/configs.git
Changes a remote. You'll rarely use this outside of changing protocols

    $ git clone --depth=1 git://github.com/Aizuko/configs.git
Quick way to clone a Github repository without needing to login

    $ git remote add upstream git@github.com:22/Aizuko/configs.git
Sets up another remote to track. Particularly important with forked branches

## Branches
Branches are a way to organize workflow into separate goals. This allows commits
for a feature that is still in development. Git recommends making a lot of cheap
branches and deleting them once merged

    $ git branch -a
Lists all the branches on the local system

#### Git checkout changes
`git checkout` was one of the most common commands to run in git, since it
handled way too much. Starting in git 2.23 the command has been split into two
new commands. `switch` deals with branches while `restore` resets files

    $ git restore file.txt
    $ git checkout file.txt
Restore a file to how it was in the `HEAD's` commit

    $ git restore --source HEAD^ file.txt
    $ git checkout HEAD^ file.txt
Restore the file to match the commit one before the `HEAD`

    $ git switch master
    $ git checkout master
Switch to the `master` branch

    $ git switch -c dev
    $ git checkout -b dev
Create a new branch called `dev`

#### Removing branches
Once a branch's goal has been achieved and merged, there's no use in keeping it
around. Having a bunch of old branches is simply confusing

    $ git branch --merged
Shows which branches have been merged. Many of these are often safe to delete

    $ git branch -d merged_branch
Deletes a branch locally. Only deletes branches that have been fully merged into
an upstream, so often the remote. There's no fear in losing commits this way

    $ git branch -D deadend_branch
    $ git branch -f -d deadend_branch
Force deletes a local branch, regardless of whether it's been merged. You can,
and likely will, lose commits this way. This should only be used for local
experimental branches that quickly hit a dead end in development

    $ git push origin --delete merged_branch
Deletes the branch on the remote repository as well

#### Tagging
Tags can be added to make referencing certain commits easier. Tags can often be
used instead of the rather complicated SHA1 to reference commits

    $ git tag -a v0.1.0 a22a398
    $ git tag -a v0.1.0 a22a398 -m "First version"
Creates an annotated tag for the commit `a22a398`. The tag will be automatically
signed

    $ git tag -a -f v0.2.0 a22a398 -m "Add compact statusline"
Overwrite previous tag for a commit with a new tag. This isn't a problem for
tags that are only local to the system. Do not attempt for remote tags

    $ git push origin v0.1.0
    $ git push origin --tags v0.1.0 v0.2.0
Push up locally created tags to the remote. Tags need to be explicitly pushed.
Note that undoing tag pushes is really hard and shouldn't be done

## Ignoring files
In general there are 2 types of files you won't want to track with git: build
artifacts and files specific to your computer. Stopping git from tracking these
is done through git ignore pattern files

    ./.gitignore
Sits in the root of a git repository as a local ignore file. This will be
committed to the repository, so other users will ignore the same files

    ./.git/info/exclude
Acts like a `.gitignore` file specific to your system's repository. It will not
be committed. Useful for random files you have lying around

    ~/.gitignore_global
A `gitignore` that applies to every repository for the user. It will not be
committed to any particular repository, so it's more similar to a git exclude
file. It doesn't need any particular name, just source it in `~/.gitconfig`:
```
[core]
	excludesfile = ~/.gitignore_global
```

`.gitignore` files use pattern matching similar to regex

    target
    target/**/*
Ignores anything in and including the `./target` directory

    target/notes_[0-9].md
    target/notes_?.md
Doesn't track any note files from 0-9, though will track anything higher, such
as `target/notes_12.md`. A `?` matches any one character, in this case also
matching `target/notes_a.md`

    !target/*_notes_*/lec_*.md
Track any lecture file in any notes directory in `target`. This can match paths
like `target/cmput_notes_1/lec_2.md` and `target/japan_notes_12/lec_passive.md`

    $ git rm --cached file.txt
In shell, removes a currently tracked file from tracking. This won't remove the
file from your system. Useful when you start ignoring a previously tracked file

[//]: # ex: set ft=markdown:tw=80: