pofl · February 8, 2019 12:22 · Feb 8, 2019 · Feb 8, 2019 · Feb 8, 2019
diff --git a/0-intro.md b/0-intro.md
@@ -10,9 +10,9 @@ Goals of this guide:
 
 - For every little facet and detail of using git there exists a blog post or StackOverflow question or both that explain that particular topic very well. Instead of re-writing everything this guide stays concise and links to the full explanations.
 
-This guide comes in two parts. Firstly, the [__guide__](https://github.com/pofl/git-guide/blob/master/docs/guide.md) itself, and secondly, a sort of [appendix](https://github.com/pofl/git-guide/blob/master/docs/rest.md), where I'll dump additional links and information in a less structured form.
+This guide comes in two parts. Firstly, the [__guide__](https://gist.github.com/pofl/a9535f0cdedd8224d46a199d29cec2a2#file-1-main-md) itself, and secondly, a sort of [appendix](https://gist.github.com/pofl/a9535f0cdedd8224d46a199d29cec2a2#file-2-appendix-md), where I'll dump additional links and information in a less structured form.
 
-[__Click here to see the guide__](https://github.com/pofl/git-guide/blob/master/docs/guide.md)
+[__Click here to see the guide__](https://gist.github.com/pofl/a9535f0cdedd8224d46a199d29cec2a2#file-1-main-md)
 
 ### Target audience
 

diff --git a/intro.md → 0-intro.md b/intro.md → 0-intro.md
diff --git a/main.md → 1-main.md b/main.md → 1-main.md
diff --git a/appendix.md → 2-appendix.md b/appendix.md → 2-appendix.md
diff --git a/appendix.md b/appendix.md
@@ -0,0 +1,58 @@
+# Mastering Git
+
+- [Tags](https://blog.daftcode.pl/how-to-become-a-master-of-git-tags-b70fbd9609d9)
+
+- `git add --patch`
+
+- `rebase` with `-p` and `-r`
+    - `-r` / `--rebase-merges` <https://git-scm.com/docs/git-rebase#_rebasing_merges>
+    - `-p` / `--preserve-merges` <https://stackoverflow.com/questions/4783599/rebasing-a-git-merge-commit>
+
+- `checkout -m`
+
+- [Set branch to current ref](https://stackoverflow.com/questions/7580542/git-set-branch-to-current-ref) (`git checkout -B <branch>
+`)
+
+- Comparison of `git add .`, `git add --all` and `git add --update`: <https://stackoverflow.com/a/26039014/9039623>
+
+- [Git Internals by Scott Chacon](https://github.com/pluralsight/git-internals-pdf) (how git works internally)
+
+- diff
+    - word-diff
+    - dir-diff
+
+- Patches in Git
+    - The output `diff` produces is the format of the Unix program 'patch' (<https://stackoverflow.com/a/8279783/9039623>)
+    - The Linux kernel uses a strange workflow around sending such patches/diffs via e-mails to other maintainers. (<https://git-scm.com/book/id/v2/Distributed-Git-Maintaining-a-Project>)
+
+- blame and `git log --follow -- filename`
+    - <https://stackoverflow.com/questions/3701404/list-all-commits-for-a-specific-file>
+
+- Configuration
+    - git log
+        https://stackoverflow.com/questions/1057564/pretty-git-branch-graphs/35075021
+    - Aliases
+    - [How to keep git log and less output on the screen](http://serebrov.github.io/html/2014-01-04-git-log-and-less-keep-output.html)
+
+- Clearing up the confusion about 'LOCAL' and 'REMOTE' during merges/rebases: https://stackoverflow.com/questions/3051461/git-rebase-keeping-track-of-local-and-remote
+
+- Git hooks
+    - https://rock-it.pl/automatic-code-quality-checks-with-git-hooks/
+
+- Tools
+    - difftool, mergetool
+        - <https://developer.atlassian.com/blog/2015/12/tips-tools-to-solve-git-conflicts/>
+    - tig
+        - <https://www.atlassian.com/blog/git/git-tig>
+    - lazygit
+        - <https://github.com/jesseduffield/lazygit>
+
+- `reflog`
+
+- bisect
+
+- rerere
+
+- <https://stackoverflow.com/questions/4044368/what-does-tree-ish-mean-in-git>
+
+- [6 Git Aha Moments](https://henrikwarne.com/2018/06/25/6-git-aha-moments/)
diff --git a/intro.md b/intro.md
@@ -0,0 +1,59 @@
+# The hop-on-hop-off guide to git
+
+This guide is intended to be your guiding light in the dark dangerous cave of learning Git.
+
+Goals of this guide:
+
+- Help you improve your git skills. No matter how much you already know about git, here you can find new things to learn.
+
+- You know the basics of git / SCM but you also know that you don't know enough. This guide lays out the track from "I know how to merge branches" to git mastery.
+
+- For every little facet and detail of using git there exists a blog post or StackOverflow question or both that explain that particular topic very well. Instead of re-writing everything this guide stays concise and links to the full explanations.
+
+This guide comes in two parts. Firstly, the [__guide__](https://github.com/pofl/git-guide/blob/master/docs/guide.md) itself, and secondly, a sort of [appendix](https://github.com/pofl/git-guide/blob/master/docs/rest.md), where I'll dump additional links and information in a less structured form.
+
+[__Click here to see the guide__](https://github.com/pofl/git-guide/blob/master/docs/guide.md)
+
+### Target audience
+
+You should fall into one of these categories:
+
+- You're already __familiar with Git to some extent__.
+    - This guide is for you. To continue we assume you know everything listed in the next chapter. If you do not know something listed there, google the words that don't sound familiar to you.
+
+- You're __new to Git__ and/or Version Control Systems in general.
+    - In this case you're better off reading a book about Git and after that return to this guide.
+        - Here is a comprehensive StacḱOverflow question+answers that covers the basics of Git and includes a list of books and guides for beginners: <https://stackoverflow.com/questions/315911/git-for-beginners-the-definitive-practical-guide>
+        - Here is a beautiful git command reference: <https://ndpsoftware.com/git-cheatsheet.html>
+        - Here is an incomplete list of git books/guides: <https://hackr.io/tutorials/learn-git>
+        - [GitHub's Git learning resources](http://try.github.io/)
+
+### Motivation
+
+I had a hard time learning Git. The first time I worked with Git, I wanted to get something done and git was an obstacle in my path to achieve a goal. I rushed the learning process. I got the basic commands down like add, commit, checkout, push etc. but then I stopped going deeper and I ended up in a pretty lost place.
+
+__Learning git takes time__. There are entire books about git that take you from the basics to the details. However, I wasn't patient enough to read those books. I already knew the basics so why would I read a book that teaches me the basics all over before it gets to the good parts? And if I skipped to the good parts what small details will I have missed that would be necessary to get a good understanding?
+
+## Prerequisite knowledge of Git
+
+This guide will not cover any of the following topics. It assumes the reader knows these.
+
+- Setting up a new repository
+
+    - `git init`
+
+- What are commits and how to commit
+
+    - Terminology: commits, index/stage, working directory
+    - Commits are identified by a unique hash which can be referred to with as little as its first six characters
+    - Commands: `status` / `add` / `commit` / `log`
+
+- What are branches and how to use them
+
+    - `diff`
+    - `branch` / `checkout` / `merge`
+
+- Beyond a local repo on your computer
+
+    - `clone` /  `remote`(s)
+    - `push` / `fetch`
diff --git a/main.md b/main.md
@@ -0,0 +1,93 @@
+# Becoming proficient with Git
+
+## Best practices
+
+- [The seven rules of a great Git commit message](https://chris.beams.io/posts/git-commit/#seven-rules)
+    - Learn these rules! The rest of this article is very informative as well.
+- [What should be in version control... and what should not.](https://hackernoon.com/what-should-be-in-version-control-d5f16e9a2bf2)
+
+
+## [The Visual Git Reference (VGR)](http://marklodato.github.io/visual-git-guide/index-en.html)
+
+- This is the mother of all informative resources about Git. Read it very carefully.
+
+## A Git repository is a directed acyclic graph (DAG) of commits
+
+- The commit DAG is frequently reported to be "the most important thing to realize about git". You should strive to _understand every git command in terms of how it manipulates the commit graph!_ The VGR is an excellent resource to understand this.
+- Have a look at the DAG of your repository with `git log --all --decorate --oneline --graph` (log adog / _"look, a dog!"_)
+- What you need to internalize is that __commits are nodes in a DAG__. All commits have one parent commit, merge commits have two parents.
+- Another concept you need to understand are references. __Branches, tags and HEAD are all references__. Which basically means they are an alias of a particular commit.
+- Examples: "`merge`creates a commit with two parent commits", "`cherry-pick` takes a list of commit hashes and applies them as patches onto HEAD" and "`reset` takes a reference to or the hash of a commit and makes the current branch point to it".
+- [HEAD is a special reference](https://blog.thoughtram.io/git/rebase-book/2015/02/10/understanding-branches-in-git.html).
+- [Relative references](https://stackoverflow.com/questions/2221658/whats-the-difference-between-head-and-head-in-git), like `HEAD~2` are very helpful too.
+
+## Rebasing
+
+- Rebasing is an alternative to merging in as far as both of them are ways to integrate two branches. A `rebase` is a special case of `cherry-pick`.
+
+### `cherry-pick`
+
+- Select commits by their hashes and apply them one-by-one onto HEAD
+- See the VGR for visual aid.
+
+### `rebase`
+
+- Rebase does the same as cherry-pick, only for entire branches automatically. The VGR explains the technical side of rebases pretty well.
+- This guide -- [Getting solid at Git rebase vs. merge](https://medium.com/@porteneuve/getting-solid-at-git-rebase-vs-merge-4fa1a48c53aa) -- explains in depth the pros and cons of rebase and merge. It's a very long post and many of its contents will also be covered in this guide. However, you should definitely add this to your read-later list.
+
+### `push --force` / `push --force-with-lease`
+
+- After you rebased a branch it contains different commits than before. Because of that `git push` will reject your changes.
+- A full explanation of the problem and why `--force-with-lease` is a better solution than `--force` can be found [here](https://developer.atlassian.com/blog/2015/04/force-with-lease/).
+
+## Working with remotes
+
+- Learn about [tracking upstream branches](https://www.git-tower.com/learn/git/faq/track-remote-upstream-branch). This link covers `git push --set-upstream` aka `git push -u`.
+    - `git branch -vva` will give you an overview of which remote branches your local branches track
+
+### How to `pull` correctly
+
+- Before turning to `pull`, let's make clear what a fast-forward merge is.
+
+- __Fast-forward merges__
+    - A fast-forward merge is the special case where a merge can be completed without creating an extra merge commit.
+    - Refer to the VGR or <https://sandofsky.com/images/fast_forward.pdf>
+
+- __`pull` vs `pull --rebase` vs `pull --ff-only`__
+    - What's the difference between `pull` and `pull --rebase`? (spoiler: `pull --rebase` is what you want to use):
+        - [When should I use `git pull --rebase`?](https://stackoverflow.com/questions/2472254/when-should-i-use-git-pull-rebase)
+        - And another article discouraging `pull`: <https://adamcod.es/2014/12/10/git-pull-correct-workflow.html>
+    - `pull` is actually considered harmful!
+        - The preferred way to get remote changes is: Use `pull --ff-only` and if it fails __consciously take appropriate actions__ with merge, rebase, cherry-pick, whatever.
+        - Read the answers to this [SO question](https://stackoverflow.com/questions/15316601/in-what-cases-could-git-pull-be-harmful)
+
+## Workflow
+
+- In order to have a broad understanding of Git let's have a look at a couple of popular usage paradigms
+
+    - A very basic introductory article on how to use branches in Git: <https://sandofsky.com/blog/git-workflow.html>
+    - [The Git flow](https://nvie.com/posts/a-successful-git-branching-model/). A very popular branching model for git.
+    - Maximum historical innformation
+
+    - [An overview of Git workflows](https://mirrors.edge.kernel.org/pub/software/scm/git/docs/gitworkflows.html)
+
+    - [Distributed Git Workflows](https://git-scm.com/book/id/v2/Distributed-Git-Distributed-Workflows)
+        - Example of a centralized workflow: Gitlab's Merge Request workflow
+        - Example of a Integration-Manager Workflow: [Fork and Pull Request Workflow](https://github.com/susam/gitpr) (GitHub's Pull Request workflow)
+        - Example of a Dictator and Lieutenants Workflow: The Linux kernel's patch-based workflow
+
+## On the importance of worrying about your commit history
+
+- [How (and why!) to keep your Git commit history clean](https://about.gitlab.com/2018/06/07/keeping-git-commit-history-clean/)
+- `git rebase -i`
+        - [Git Interactive Rebase, Squash, Amend and Other Ways of Rewriting History](https://robots.thoughtbot.com/git-interactive-rebase-squash-amend-rewriting-history)
+
+- Undoing things in Git
+    - <https://www.atlassian.com/git/tutorials/undoing-changes>
+    - <https://hackernoon.com/when-to-use-git-reset-git-revert-git-checkout-dc4824795d9>
+    - <https://www.atlassian.com/git/tutorials/resetting-checking-out-and-reverting>
+
+- `squash` / `commit --fixup` / `rebase --auto-squash`
+    - <https://robots.thoughtbot.com/autosquashing-git-commits>
+
+- A clean commit history is nice, but sometimes you end up wasting time on it. So keep in mind that sometimes branching and merging is a good enough workflow. Also, here's an opinion that [you should stop using rebase](https://medium.com/@fredrikmorken/why-you-should-stop-using-git-rebase-5552bee4fed1).
No results found