Move Git documents to subfolder

docs/git/basics.md

@@ -0,0 +1,82 @@
+# Git 101
+
+We are using git version 2.7.x, but any version should be good.
+It's recommended to learn `git` command line tool for full cross-platform expirience.
+
+There are (too) many git tutorials on the internet.
+Here we post referrences to our favorites.
+
+## Install
+
+#### Windows
+
+Install [Git for Windows][].
+
+During the install process, choose these recommended settings:
+
+* Use Git from the Windows Command Prompt
+* Use OpenSSH
+* Checkout Windows-style, commit Unix-style line endings
+* Use Windows' default console window
+* Enable file system caching
+
+#### Linux
+
+Install via the package manager:
+
+```sh
+sudo apt-get install git
+```
+
+## Interactive tutorials
+
+#### Hello world
+
+If you're new to Git, learn the following commands: `checkout`, `branch`,
+`pull`, `push`, `merge`.
+
+Use GitHub's [Hello World][] to learn how to create a feature branch, commit
+changes, and issue a pull request.
+
+[hello world]: https://guides.github.com/activities/hello-world/
+
+#### Githug
+
+[Githug](https://github.com/Gazler/githug) is a great gamefied way to learn git in couple hours.
+After finishing 50+ real-world scenarios you will have a pretty good idea about what and when you can do with git.
+
+## Cheatsheets
+
+#### Git pretty
+[So you have a mess on your hands?](http://justinhileman.info/article/git-pretty/)
+
+## Scenarios
+
+#### Sync your local repo
+
+Don't commit your changes directly to master.
+It would make workflow messy.
+
+Always create a branch for your changes.
+
+```sh
+# switch to master branch
+
+# fetch updates all remote branch references in the repo and all submodules
+# --all : tells it to do it for all remotes (handy, when you use your fork)
+# -p : tells it to remove obsolete remote branch references (when they are removed from remote)
+git fetch --all -p
+
+# pull updates your local files
+# you should call this command ONLY from master branch
+git pull origin master
+
+# update submodules
+git submodule update --recursive 
+```
+
+Then switch to your branch and do rebase
+
+```
+git rebase master
+```

docs/git/committing.md

@@ -0,0 +1,49 @@
+#Commit Dance
+Most of the time, you're going to be working in a submodule (say src/monad/monad/engine).
+The submodule has a relationship to the SuperProject  (PowerShell), but in order to be sure that CI is
+notified about changes in a submodule, you need be sure that this is reflected as a pull request in the SuperProject.
+
+**Scenario**: Jim fixes issue in `src/monad/monad/src/engine/DataStoreAdapter.cs`
+
+the following takes place in the submodule:
+* Make the code change
+* Commit the code change in a feature branch. Branch name in form `<alias>/<moniker>`, i.e `jim/colon-drive`.
+* Push the branch (in the submodule project): `git push origin jim/colon-drive`
+* Pull request in the submodule to notify people via email about new code review. 
+
+Then, in the SuperProject (PowerShell) 
+* `git status` should show a change of submodule **as a whole** (not individual files). _In my case_ it is `src/monad`.
+* `git diff` should show something like
+
+```diff
+index 1ba8dd4..ed5d202 160000
+--- a/src/monad
++++ b/src/monad
+@@ -1 +1 @@
+-Subproject commit 1ba8dd4f721f2cd4363f64609515ec1600378c30
++Subproject commit ed5d2022617f317a78a8a57e2c257c8e29cddbd5
+```
+
+* Commit that change into a branch with the same name, i.e. `jim/colon-drive`
+* Push the branch (in the SuperProject): `git push origin jim/colon-drive`
+* Pull request in the superproject to kick-in CI build and notify people. Reference submodule pull-request in the PR message to make navigation between two simpler.
+
+### Commands log
+
+Here is a transcript of command Jim used:
+```
+cd $HOME/PowerShell/src/monad/monad/src/engine
+vi DataStoreAdapter.cs
+git checkout -b jim/colon-drive
+git commit -a
+git push origin jim/colon-drive
+```
+then I went to the web interface and did the pull request *in the submodule*. After that, back to the commandline:
+```
+cd $HOME/PowerShell
+git checkout -b jim/colon-drive
+git commit -a
+git push origin jim/colon-drive
+```
+and back to the web interface for the pull request *in the superproject*.
+

docs/git/source-depot.md

@@ -0,0 +1,52 @@
+# Quick git-primer for sd users
+
+There few important conceptual differences with **sd**.
+This list tries to bridge the gap
+
+* When you do `git commit` changes are stored in your local clone of the repo. 
+To Submit them, you need to do `git push`.
+* Forks are just a way to store branches. 
+You can push branch to the original repo (if you have permissions) or to the fork. 
+There is no principal difference.
+* Most of the git complications come from the fact that you need to do integrations by yourself.
+
+
+The Microsoft Open Source Hub [article](https://opensourcehub.microsoft.com/articles/git-for-sd-users) for other details.
+
+### Rosetta stone
+
+
+#### Concepts
+
+| Concept | SD termin | Git termin |
+|---------|----|----------------|
+| Your local copy | enlistment | cloned repo |
+| Code changes  | changelist | commit |
+| Way to preserve changes locally | dpk | local branch |
+
+
+#### Commands 
+
+Before running a git command for the first time, try
+
+```sh
+git help <command name>
+```
+
+To read about flags and the overall meaning.
+
+|Scenarios | SD command | Git commmand |
+|---------|----|----------------|
+| Get the code at the first place | sd enlist | git clone |
+| Sync changes  |  sd sync | git pull |
+| Add new files |  sd add  | git add |
+| Modify existing files | sd edit | git add |
+| Remove existing files | sd delete | git rm |
+| Copy/Rename files | sd branch | git mv |
+| Commit to local |   | git commit |
+| Submit changes | sd submit | git push |
+| Revert changes | sd revert | git checkout |
+| Undo submitted changes | sd undo | git revert |
+| Diff tool | odd | git diff |
+| Clean enlistment  |  build nuke | git clean |
+