Add documentation

Author: Kobzol

README.md

@@ -1,3 +1,56 @@
 # Josh sync utilities
 This repository contains a binary utility for performing [Josh](https://github.com/josh-project/josh)
 synchronizations (pull and push) of Josh subtrees in the [rust-lang/rust](https://github.com/rust-lang/rust) repository.
+
+## Installation
+You can install the binary `josh-sync` tool using the following command:
+
+```bash
+$ cargo install --locked --git https://github.com/rust-lang/josh-sync
+```
+
+## Creating config file
+
+First, create a configuration file for a given subtree repo using `josh-sync init`. The config will be created under the path `josh-sync.toml`. Modify the file to fill in the name of the subtree repository (e.g. `stdarch`) and its relative path in the main `rust-lang/rust` repository (e.g. `library/stdarch`).
+
+## Performing pull
+
+A pull operation fetches changes to the subtree subdirectory that were performed in `rust-lang/rust` and merges them into the subtree repository. After performing a pull, a pull request is sent against the *subtree repository*. We *pull from rustc*.
+
+1) Checkout the latest default branch of the subtree
+2) Create a new branch that will be used for the subtree PR, e.g. `pull`
+3) Run `josh-sync pull`
+4) Send a PR to the subtree repository
+    - Note that `josh-sync` can do this for you if you have the [gh](https://cli.github.com/) CLI tool installed.
+
+## Performing push
+
+A push operation takes changes performed in the subtree repository and merges them into the subtree subdirectory of the `rust-lang/rust` repository. After performing a push, a push request is sent against the *rustc repository*. We *push to rustc*.
+
+1) Checkout the latest default branch of the subtree
+2) Run `josh-sync pull <your-github-username> <branch>`
+    - The branch with the push contents will be created in `https://github.com/<your-github-username>/rust` fork, in the `<branch>` branch.
+3) Send a PR to `rustc`
+
+## Git pecularities
+
+NOTE: If you use Git/SSH protocol to push to your fork of `rust-lang/rust`,
+ensure that you have this entry in your Git config,
+else the 2 steps that follow would prompt for a username and password:
+
+```
+[url "[email protected]:"]
+insteadOf = "https://github.com/"
+```
+
+### Minimal git config
+
+For simplicity (ease of implementation purposes), the josh-sync script simply calls out to system git. This means that the git invocation may be influenced by global (or local) git configuration.
+
+You may observe "Nothing to pull" even if you *know* rustc-pull has something to pull if your global git config sets `fetch.prunetags = true` (and possibly other configurations may cause unexpected outcomes).
+
+To minimize the likelihood of this happening, you may wish to keep a separate *minimal* git config that *only* has `[user]` entries from global git config, then repoint system git to use the minimal git config instead. E.g.
+
+```
+GIT_CONFIG_GLOBAL=/path/to/minimal/gitconfig GIT_CONFIG_SYSTEM='' josh-sync ...
+```