rename adv_guides to tutorials

.gitmodules

@@ -1,3 +1,3 @@
-[submodule "docs/adv_guides/learngit"]
-	path = docs/adv_guides/learngit
+[submodule "docs/tutorials/learngit"]
+	path = docs/tutorials/learngit
 	url = https://github.com/benharri/learngit.git

docs/adv_guides/learngit

@@ -1 +0,0 @@
-Subproject commit 5b04ae0c15a0764a32646b5fb10c2478e03d12b9

docs/tutorials/learngit/README.md

@@ -0,0 +1,122 @@
+# learngit
+
+This is a compilation of notes, tips and a getting started guide to [`git`](https://git-scm.com). Please feel free to open a pull request or fork it for yourself!
+
+### table of contents
+**[home](README.md)** •
+[glossary](glossary.md) •
+[common commands](common_commands.md) •
+[branching strategies](branching_strategies.md) •
+[troubleshooting](troubleshooting.md) •
+[ssh setup](ssh_setup.md)
+
+---
+
+### on this page
+* [getting set up](README.md#getting-set-up)
+* [making your first repo](README.md#making-your-first-repo)
+* [syncing your changes with others](README.md#syncing-your-changes-with-others)
+* [external resources](README.md#external-resources)
+
+---
+
+
+# here we go!
+
+This is not meant to be a complete guide to git. Just some notes that I've gathered over the years of using git that might be helpful to share with others.
+
+## getting set up
+
+1. Download [`git`](https://git-scm.com) and install it.
+    * Some OSes/distros have `git` available through a package manager like `brew`, `apt`, or `pacman`. That will be the easiest option.
+1. Windows: open git bash (or any command prompt if you chose to install git system-wide).
+    All other systems: open a terminal of your choice.
+1. Make sure that the install worked correctly by typing `git --version`
+1. Configure git with your name and email address:
+    * `git config --global user.name "Your Name Here"`
+    * `git config --global user.email "name@domain.tld"`
+
+You're ready to `git` gud!
+
+![git gud](img/gitgud.jpeg)
+
+
+## making your first repo
+
+1. Create a new, empty folder ([directory](glossary.md#directory) in git and unix speak)
+    * the command to make a new folder is `mkdir <directory_name>`
+1. Open or move to that folder in a command prompt that has git (look for git bash in the start menu if you're having trouble with this one)
+    * the command to move between directories is `cd <directory_name>`
+1. Once you're in that directory, execute `git init`. this command creates a `.git` folder inside the current folder, which is where `git` stores all the information and history for the repo.
+1. Create and edit some files
+    * for example: `echo "foo bar" >> foobar.txt`
+1. Check `git status` you should see something like this:
+    ![status of new repo](img/new-repo-status.png)
+    * at this point, our [working tree](glossary.md#working-tree) is ["dirty"](glossary.md#dirty), meaning that there are unsaved changes in the directory.
+1. At this point, you need to add the changes to the [staging area](glossary.md#staging-area) with the `git add` command
+    * you can add individual files by name (`git add foobar.txt`) or all changes to the working tree with the command option `--all`
+1. Once the files are staged, you are now ready to [`commit`](common_commands.md#commit) the changes. every commit requires a message, which can be specified with the `-m` option. if you don't give a message with the [`commit`](common_commands.md#commit) command, `git` will open your file editor and ask you to enter one.
+    ![add and commit changes](img/add-and-commit.png)
+
+Now you have a repo with one commit in it!
+
+
+## syncing your changes with others
+
+Now we get to have some real fun. The whole point of a distributed version control system is to allow many people to be working on the same code at once.
+
+There are many ways to collaborate on a `git` repo. The simplest way to share a repo is to use the `--bare` option with the [`init`](common_commands.md#init) command.
+
+> Bare repos are generally stored on a server that all users have SSH access to: once the repo is created on the server, each person can [`clone`](common_commands.md#clone) a copy to their local machine like this: `git clone user@servername:path/to/repo`
+
+Otherwise, there are dozens of git hosting options, the most popular of which is [github](https://github.com), which hosts the majority of all open source projects.
+
+Another cool option is [gitlab](https://gitlab.com). They offer unlimited private repos in addition to public ones.
+
+Let's take a look at syncing your repo with github (or any other git hosting location - just swap out the URLs).
+
+1. [Create the repo](https://github.com/new) (this assumes you're using GitHub)
+1. Set up the [`remote`](glossary.md#remote)s
+    * This depends on whether you have already created the repository locally. once you have created the repo on github, it will display some tips for which commands to use
+    * For an existing repo: `git remote add origin git@github.com:username/reponame` OR `git remote add origin https://github.com/username/reponame` depending on your [SSH key setup](ssh_setup)
+    * If the repo doesn't exist yet, [`clone`](common_commands.md#clone) the repo like this: `git clone git@github.com:username/reponame`
+    * A repo can have and use more than one remote. you can see the current remotes with this command: `git remote -v`
+1. Before you can sync your changes, there needs to be at least one commit in the repo (not a problem for pre-existing repos). Create one now if you haven't.
+1. Now you can [`push`](common_commands.md#push) your commit history to the remote repo! use this command: `git push origin --all` to push all branches and commits to the remote (assuming that the remote is named `origin`)
+
+To get changes that have other people have pushed the the repo while you were away, use the [`fetch`](common_commands.md#fetch) and [`merge`](common_commands.md#merge) commands. since this is such a common operation, [`pull`](common_commands.md#pull) was created as a shortcut for `git fetch` immediately followed by `git merge`.
+
+If you haven't made any changes since the last time you `pull`ed the latest changes, it's usually a good idea to [`rebase`](common_commands.md#pull). This will replay all of the work that has been done on top of the current repo state, avoiding extra merge commits in the repo history. Just use `git pull --rebase`.
+
+
+
+---
+
+## external resources
+So you want to learn more?
+Here are some more resources!
+
+### articles and documentation
+* [git flight rules](https://github.com/k88hudson/git-flight-rules)
+* [progit book](https://git-scm.com/book/en/v2)
+* [github interactive tutorial](https://try.github.io)
+* [learn enough git to be dangerous](https://www.learnenough.com/git-tutorial)
+* [atlassian git tutorials](https://www.atlassian.com/git/tutorials)
+* [github documentation](https://help.github.com)
+
+### tools and apps
+* [sourcetree app](https://sourcetreeapp.com) (a visual GUI tool for working with git repos: great for people who don't feel quite at home on the command line)
+* [github desktop](https://desktop.github.com) (an alternate GUI by github)
+
+
+---
+
+## contact me
+Shoot me a message somewhere on the interwebz
+
+* [email](mailto:ben@tilde.team)
+* [my site](https://tilde.team/~ben/)
+* [github](https://github.com/benharri)
+* irc (ben on [tilde.chat](https://tilde.chat/), benharri on [freenode](https://freenode.net/))
+
+Thanks for checking out my git guide!

docs/tutorials/learngit/_config.yml

@@ -0,0 +1 @@
+theme: jekyll-theme-minimal

docs/tutorials/learngit/branching_strategies.md

@@ -0,0 +1,27 @@
+# branching strategies
+
+### table of contents
+[home](README.md) •
+[glossary](glossary.md) •
+[common commands](common_commands.md) •
+**[branching strategies](branching_strategies.md)** •
+[troubleshooting](troubleshooting.md) •
+[ssh setup](ssh_setup.md)
+
+---
+
+## Branch to env mapping
+* [Env branch mapping](https://www.wearefine.com/mingle/env-branching-with-git/)
+* [gitlab flow](https://docs.gitlab.com/ee/workflow/gitlab_flow.html)
+* [oneflow](http://endoflineblog.com/oneflow-a-git-branching-model-and-workflow) (gitflow with one instead of two long-living branches)
+
+### branch -> env
+* prod -> prod
+* mo -> mo
+* qa -> qa
+* **master** -> dev (feature branches are created from master)
+    * specific tagged commits can be deployed from master to any of the dev or qa envs
+
+  Env configs can be generated with a combination of env vars and other source-controlled files
+
+

docs/tutorials/learngit/common_commands.md

@@ -0,0 +1,132 @@
+# common git commands
+
+These are commands and options that I use frequently. See the linked documentation for more options and information.
+
+### table of contents
+[home](README.md) •
+[glossary](glossary.md) •
+**[common commands](common_commands.md)** •
+[branching strategies](branching_strategies.md) •
+[troubleshooting](troubleshooting.md) •
+[ssh setup](ssh_setup.md)
+
+---
+
+
+## [add](https://git-scm.com/docs/git-add)
+> `git add [--all] [<files>]`
+
+Add files from the working tree to the staging area. [`commit`](#commit) operates on the staging area.
+
+Try interactive staging: `git add -i`
+
+
+## [branch](https://git-scm.com/docs/git-commit)
+> `git branch [<branch>]`
+
+Show branches and create new ones.
+
+
+## [checkout](https://git-scm.com/docs/git-checkout)
+> `git checkout [<branch>]`
+
+Switch branches or restore working tree files.
+
+The `-b` switch creates the branch if it doesn't exist and switches to it.
+
+
+## [clone](https://git-scm.com/docs/git-clone)
+> `git clone [<remote_url>] [directory_to_clone_into]`
+
+Download a copy of a remote repository from a server.
+
+
+## [commit](https://git-scm.com/docs/git-commit)
+> `git commit [-a] [-m "commit message here"]`
+
+Create a snapshot of the staging area. Record staged changes.
+
+The `-a` switch will add all modified and deleted files (will not pick up new files that have been added to the repo) to the staging area before committing.
+
+
+## [diff](https://git-scm.com/docs/git-diff)
+> `git diff [<from_path-spec>]..[<to_path-spec>]`
+
+Show changes by line. With no arguments, `diff` shows all unstaged changes.
+
+Other uses would be comparing changes between branches or between a range of commits (referred to by their hashes, which you can see with [`log`](#log)).
+
+
+## [fetch](https://git-scm.com/docs/git-fetch)
+> `git fetch [<repository> [<refspec>]]`
+
+Download objects and refs from another (usually remote) repository.
+
+
+## [init](https://git-scm.com/docs/git-init)
+> `git init [--bare] [--shared] [<directory>]`
+
+Create an empty repo or reinitialize an existing one.
+
+
+## [log](https://git-scm.com/docs/git-log)
+> `git log [<revision range>]`
+
+Show commit logs. There are a lot of options here. Check out the documentation.
+
+Here are some of the log options that I use often. Some tips were taken from [git-tips](https://github.com/git-tips/tips)
+
+All commits since forking from master
+* `git log --no-merges --stat --reverse master..`
+
+Visualize the history as a tree
+* `git log --pretty=oneline --graph --decorate --all`
+
+![pretty oneline](img/pretty-oneline.png)
+
+List changes specific to a certain file
+* `git log --follow -p -- <file_path>`
+
+
+## [merge](https://git-scm.com/docs/git-merge)
+> `git merge [<branch>]`
+
+Join two or more development histories together.
+
+`merge` incorporates changes from the named commits provided as arguments into the current branch.
+
+Sometimes you will have changed the same line as someone else. This will result in a merge conflict. Some GUI clients have tools to help resolve merge conflicts, but it is good to know how to do it manually.
+
+```
+Here are lines that are either unchanged from the common
+ancestor, or cleanly resolved because only one side changed.
+<<<<<<< yours:sample.txt
+Conflict resolution is hard;
+let's go shopping.
+=======
+Git makes conflict resolution easy.
+>>>>>>> theirs:sample.txt
+And here is another line that is cleanly resolved or unmodified.
+```
+* This is what you will see as the result of a merge conflict. Simply keep the lines you would like, remove the conflict markers, and commit the result.
+
+See the documentation for more info on how to resolve merge conflicts.
+
+
+## [pull](https://git-scm.com/docs/git-pull)
+> `git pull [--rebase] [--ff] [--no-ff] [<remote name>] [<branch name>]`
+
+`pull` is a synonym for [`fetch`](#fetch) followed immediately by a [`merge`](#merge). It's a nice shortcut for that.
+
+Use the `--rebase` option when you haven't made any changes and want to get the latest changes that others have pushed to the remote.
+
+To sync with remote and overwrite local changes:
+> `git fetch origin && git reset --hard origin/master && git clean -f -d`
+
+
+## [push](https://git-scm.com/docs/git-push)
+> `git push [-u] [<remote name>] [<branch name>]`
+
+The `-u` option will set the following branch and remote to the default upstream. This means you can simply do `git pull` without the [refspec](glossary.md#refspec).
+
+

docs/tutorials/learngit/glossary.md

@@ -0,0 +1,114 @@
+# git glossary
+
+> [source (git-scm.com)](https://git-scm.com/book/en/v2) (unless otherwise noted)
+
+### table of contents
+[home](README.md) •
+**[glossary](glossary.md)** •
+[common commands](common_commands.md) •
+[branching strategies](branching_strategies.md) •
+[troubleshooting](troubleshooting.md) •
+[ssh setup](ssh_setup.md)
+
+---
+
+## [branch](https://git-scm.com/book/en/v1/Git-Branching-What-a-Branch-Is)
+To really understand the way Git does branching, we need to take a step back and examine how Git stores its data. As you may remember from Chapter 1, Git doesn’t store data as a series of changesets or deltas, but instead as a series of snapshots.
+
+Running [`git commit`](common_commands#commit) checksums all project directories and stores them as tree objects in the Git repository. Git then creates a commit object that has the metadata and a pointer to the root project tree object so it can re-create that snapshot when needed.
+
+A branch in Git is simply a lightweight movable pointer to one of these commits. The default branch name in Git is master. As you initially make commits, you’re given a master branch that points to the last commit you made. Every time you commit, it moves forward automatically.
+
+
+## [checkout](common_commands#checkout)
+Checking out is the operation of switching the working tree to the state at a given snapshot, which is usually the HEAD of another branch.
+
+
+## commit
+A commit is a snapshot of all tracked files in the repo.
+
+
+## directory
+Also known as a folder.
+
+
+## dirty
+> [source](https://stackoverflow.com/questions/20642980/does-git-dirty-mean-files-not-staged-or-not-committed-glossary-conflict)
+
+The "right" definition is, I think, that your tree is "clean" if there are no changes to commit and no changes between "tree staged for commit" (contents of index) and "work directory". However, it's reasonable to ask separately whether the index is clean (i.e., there is nothing staged for commit) and/or the work-tree is clean (unchanged) with respect to "the staging area" or "the HEAD commit".
+
+
+## distributed version control system
+A Distributed Version Control System (DVCS) differs from traditional VCS systems in that every user has a copy of the entire repo, including the history and all branches.
+
+A connection to a central server is not required to work on a project. Changes and conflicts can be resolved later when the diverging histories are [`merge`](common_commands#merge)d later on.
+
+
+## [gitignore](https://git-scm.com/docs/gitignore)
+Specifies intentionally untracked files to ignore.
+
+A `.gitignore` file in the root of the repository contains a list of patterns that should not be tracked.
+
+See the documentation for more information on ignore patterns.
+
+Tracked files that you would like to ignore can be deleted with `git rm --cached .` and then re-added with `git add .`
+
+
+## [hash](https://git-scm.com/docs/gitglossary#def_SHA1)
+The unique identifier of an object. The object name is usually represented by a 40 character hexadecimal string. Also colloquially called SHA-1.
+
+
+## master
+Master is the name given to the default branch of a repository.
+
+Whenever you create a Git repository, a branch named "master" is created, and becomes the active branch. In most cases, this contains the local development, though that is purely by convention and is not required.
+
+
+## origin
+Origin is the name given to the default remote. It is set automatically when using [`git clone`](common_commands#clone), and recommended when setting up the remote for an existing repo.
+
+
+## [pathspec](https://git-scm.com/docs/gitglossary#gitglossary-aiddefpathspecapathspec)
+Pattern used to limit paths in Git commands.
+
+Pathspecs are used on the command line of `git ls-files`, `git ls-tree`, `git add`, `git grep`, `git diff`, `git checkout`, and many other commands to limit the scope of operations to some subset of the tree or worktree. See the documentation of each command for whether paths are relative to the current directory or toplevel. The pathspec syntax is as follows:
+
+* any path matches itself
+
+* the pathspec up to the last slash represents a directory prefix. The scope of that pathspec is limited to that subtree.
+
+* the rest of the pathspec is a pattern for the remainder of the pathname. Paths relative to the directory prefix will be matched against that pattern using fnmatch(3); in particular, * and ? can match directory separators.
+
+For example, Documentation/*.jpg will match all .jpg files in the Documentation subtree, including Documentation/chapter_1/figure_1.jpg.
+
+A pathspec that begins with a colon : has special meaning. In the short form, the leading colon : is followed by zero or more "magic signature" letters (which optionally is terminated by another colon :), and the remainder is the pattern to match against the path. The "magic signature" consists of ASCII symbols that are neither alphanumeric, glob, regex special characters nor colon. The optional colon that terminates the "magic signature" can be omitted if the pattern begins with a character that does not belong to "magic signature" symbol set and is not a colon.
+
+In the long form, the leading colon : is followed by a open parenthesis (, a comma-separated list of zero or more "magic words", and a close parentheses ), and the remainder is the pattern to match against the path.
+
+A pathspec with only a colon means "there is no pathspec". This form should not be combined with other pathspec.
+
+
+## [refspec](https://git-scm.com/docs/gitglossary#gitglossary-aiddefrefaref)
+A name that begins with refs/ (e.g. refs/heads/master) that points to an object name or another ref (the latter is called a symbolic ref). For convenience, a ref can sometimes be abbreviated when used as an argument to a Git command; see gitrevisions[7] for details. Refs are stored in the repository.
+
+The ref namespace is hierarchical. Different subhierarchies are used for different purposes (e.g. the refs/heads/ hierarchy is used to represent local branches).
+
+There are a few special-purpose refs that do not begin with refs/. The most notable example is HEAD.
+
+
+## [remote](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes)
+Remote repositories are versions of your project that are hosted on the Internet or network somewhere. You can have several of them, each of which generally is either read-only or read/write for you. Collaborating with others involves managing these remote repositories and pushing and pulling data to and from them when you need to share work.
+
+
+## [repository](https://git-scm.com/docs/gitglossary#def_repository)
+A collection of refs together with an object database containing all objects which are reachable from the refs, possibly accompanied by meta data from one or more porcelains. A repository can share an object database with other repositories via alternates mechanism.
+
+
+## [staging area](https://softwareengineering.stackexchange.com/questions/119782/what-does-stage-mean-in-git)
+source: [stack exchange](https://softwareengineering.stackexchange.com/questions/119782/what-does-stage-mean-in-git)
+
+To stage a file is simply to prepare it finely for a commit. Git, with its index allows you to commit only certain parts of the changes you've done since the last commit. Say you're working on two features - one is finished, and one still needs some work done. You'd like to make a commit and go home (5 o'clock, finally!) but wouldn't like to commit the parts of the second feature, which is not done yet. You stage the parts you know belong to the first feature, and commit. Now your commit is your project with the first feature done, while the second is still in work-in-progress in your working directory.
+
+## [working tree](https://git-scm.com/docs/gitglossary#gitglossary-aiddefworkingtreeaworkingtree)
+The tree of actual checked out files. The working tree normally contains the contents of the HEAD commit’s tree, plus any local changes that you have made but not yet committed.
+

docs/tutorials/learngit/ssh_setup.md

@@ -0,0 +1,30 @@
+# ssh key setup for git
+
+### table of contents
+[home](README.md) •
+[glossary](glossary.md) •
+[common commands](common_commands.md) •
+[branching strategies](branching_strategies.md) •
+[troubleshooting](troubleshooting.md) •
+**[ssh setup](ssh_setup.md)**
+
+---
+
+
+Using SSH authentication for communicating with remote repos is generally easier than using https. Sometimes it's required for certain repos or by rules set at the hosting level.
+
+Here's how to get set up with SSH keys
+
+1. Create an SSH public/private key pair (skip this if you already have one!)
+    1. open git bash (or any other terminal that has git available)
+    1. type `ssh-keygen` and press enter
+        * press enter to answer each of the following questions with the default answers
+    1. as long as you saved your SSH key to the default location, enter the following command: `cat ~/.ssh/id_rsa.pub`
+    1. highlight and copy the output (starts with `ssh-rsa` and ends with `username@computer_name`)
+    1. navigate to your SSH key settings on your git hosting and add your key to your profile
+1. Clone or add the remote to an existing repo per the instructions on the project page using the ssh URL scheme (instead of `https://`)
+    * `git clone git@gitawse1.hagerty.com:<username>/<project>`
+    * `git remote add origin git@gitawse1.hagerty.com:<username>/<project>`
+1. Profit??$?
+
+> You should now be able to use SSH URLs for connections between your terminal and the remote that you copied the key to

docs/tutorials/learngit/troubleshooting.md

@@ -0,0 +1,25 @@
+# troubleshooting
+
+### table of contents
+[home](README.md) •
+[glossary](glossary.md) •
+[common commands](common_commands.md) •
+[branching strategies](branching_strategies.md) •
+**[troubleshooting](troubleshooting.md)** •
+[ssh setup](ssh_setup.md)
+
+---
+
+
+ssh warnings remote key
+
+missing branches
+
+warnings
+
+line endings
+
+pull request flow
+
+ui flow
+

mkdocs.yml

@@ -6,8 +6,8 @@ repo_url: https://git.envs.net/envs/help
 theme: cyborg
 
 nav:
-- home: 'index.md'
-- faq: 'faq.md'
+- home: index.md
+- faq: faq.md
 - basic help: help.md
 - user guide:
     - email: mail.md
@@ -17,11 +17,11 @@ nav:
     - gopher: gopher.md
     - gemini: gemini.md
     - finger: finger.md
-- advanced guides:
+- tutorials:
     - learn git:
-        - home: adv_guides/learngit/README.md
-        - glossary: adv_guides/learngit/glossary.md
-        - common commands: adv_guides/learngit/common_commands.md
-        - branching strategies: adv_guides/learngit/branching_strategies.md
-        - troubleshooting: adv_guides/learngit/troubleshooting.md
-        - ssh setup: adv_guides/learngit/ssh_setup.md
+        - home: tutorials/learngit/README.md
+        - glossary: tutorials/learngit/glossary.md
+        - common commands: tutorials/learngit/common_commands.md
+        - branching strategies: tutorials/learngit/branching_strategies.md
+        - troubleshooting: tutorials/learngit/troubleshooting.md
+        - ssh setup: tutorials/learngit/ssh_setup.md