*: Improve docs on examples, compatibility and extensibility

Fixes #777

Signed-off-by: Paulo Gomes <pjbgf@linux.com>

3 files changed, 315 insertions, 111 deletions

diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md
index 2a72b50..afd4f03 100644
--- a/COMPATIBILITY.md
+++ b/COMPATIBILITY.md
@@ -1,111 +1,233 @@
-Supported Capabilities
-======================
-
-Here is a non-comprehensive table of git commands and features whose equivalent
-is supported by go-git.
-
-| Feature                               | Status | Notes |
-|---------------------------------------|--------|-------|
-| **config**                            |
-| config                                | ✔ | Reading and modifying per-repository configuration (`.git/config`) is supported. Global configuration (`$HOME/.gitconfig`) is not. |
-| **getting and creating repositories** |
-| init                                  | ✔ | Plain init and `--bare` are supported. Flags `--template`, `--separate-git-dir` and `--shared` are not. |
-| clone                                 | ✔ | Plain clone and equivalents to `--progress`,  `--single-branch`, `--depth`, `--origin`, `--recurse-submodules` are supported. Others are not. |
-| **basic snapshotting** |
-| add                                   | ✔ | Plain add is supported. Any other flags aren't supported |
-| status                                | ✔ |
-| commit                                | ✔ |
-| reset                                 | ✔ |
-| rm                                    | ✔ |
-| mv                                    | ✔ |
-| **branching and merging** |
-| branch                                | ✔ |
-| checkout                              | ✔ | Basic usages of checkout are supported. |
-| merge                                 | ✖ |
-| mergetool                             | ✖ |
-| stash                                 | ✖ |
-| tag                                   | ✔ |
-| **sharing and updating projects** |
-| fetch                                 | ✔ |
-| pull                                  | ✔ | Only supports merges where the merge can be resolved as a fast-forward. |
-| push                                  | ✔ |
-| remote                                | ✔ |
-| submodule                             | ✔ |
-| **inspection and comparison** |
-| show                                  | ✔ |
-| log                                   | ✔ |
-| shortlog                              | (see log) |
-| describe                              | |
-| **patching** |
-| apply                                 | ✖ |
-| cherry-pick                           | ✖ |
-| diff                                  | ✔ | Patch object with UnifiedDiff output representation |
-| rebase                                | ✖ |
-| revert                                | ✖ |
-| **debugging** |
-| bisect                                | ✖ |
-| blame                                 | ✔ |
-| grep                                  | ✔ |
-| **email** ||
-| am                                    | ✖ |
-| apply                                 | ✖ |
-| format-patch                          | ✖ |
-| send-email                            | ✖ |
-| request-pull                          | ✖ |
-| **external systems** |
-| svn                                   | ✖ |
-| fast-import                           | ✖ |
-| **administration** |
-| clean                                 | ✔ |
-| gc                                    | ✖ |
-| fsck                                  | ✖ |
-| reflog                                | ✖ |
-| filter-branch                         | ✖ |
-| instaweb                              | ✖ |
-| archive                               | ✖ |
-| bundle                                | ✖ |
-| prune                                 | ✖ |
-| repack                                | ✖ |
-| **server admin** |
-| daemon                                | |
-| update-server-info                    | |
-| **advanced** |
-| notes                                 | ✖ |
-| replace                               | ✖ |
-| worktree                              | ✖ |
-| annotate                              | (see blame) |
-| **gpg** |
-| git-verify-commit                     | ✔ |
-| git-verify-tag                        | ✔ |
-| **plumbing commands** |
-| cat-file                              | ✔ |
-| check-ignore                          | |
-| commit-tree                           | |
-| count-objects                         | |
-| diff-index                            | |
-| for-each-ref                          | ✔ |
-| hash-object                           | ✔ |
-| ls-files                              | ✔ |
-| merge-base                            | ✔ | Calculates the merge-base only between two commits, and supports `--independent` and `--is-ancestor` modifiers; Does not support `--fork-point` nor `--octopus` modifiers. |
-| read-tree                             | |
-| rev-list                              | ✔ |
-| rev-parse                             | |
-| show-ref                              | ✔ |
-| symbolic-ref                          | ✔ |
-| update-index                          | |
-| update-ref                            | |
-| verify-pack                           | |
-| write-tree                            | |
-| **protocols** |
-| http(s):// (dumb)                     | ✖ |
-| http(s):// (smart)                    | ✔ |
-| git://                                | ✔ |
-| ssh://                                | ✔ |
-| file://                               | partial | Warning: this is not pure Golang. This shells out to the `git` binary. |
-| custom                                | ✔ |
-| **other features** |
-| gitignore                             | ✔ |
-| gitattributes                         | ✖ |
-| index version                         | |
-| packfile version                      | |
-| push-certs                            | ✖ |
+# Supported Features
+
+Here is a non-comprehensive table of git commands and features and their
+compatibility status with go-git.
+
+## Getting and creating repositories
+
+| Feature | Sub-feature | Status | Notes | Examples |
+|---|---|---|---|---|
+| `init` | | ✅ | | |
+| `init` | `--bare` | ✅ | | |
+| `init` | `--template` <br/> `--separate-git-dir` <br/> `--shared` | ❌ | | |
+| `clone` | | ✅ | | - [PlainClone](_examples/clone/main.go) |
+| `clone` | Authentication: <br/> - none <br/> - access token <br/> - username + password <br/> - ssh | ✅ | | - [clone ssh](_examples/clone/auth/ssh/main.go) <br/> - [clone access token](_examples/clone/auth/basic/access_token/main.go) <br/> - [clone user + password](_examples/clone/auth/basic/username_password/main.go) |
+| `clone` | `--progress` <br/> `--single-branch` <br/> `--depth` <br/> `--origin` <br/> `--recurse-submodules` | ✅ | | - [recurse submodules](_examples/clone/main.go) <br/> - [progress](_examples/progress/main.go) |
+
+## Basic snapshotting
+
+| Feature | Sub-feature | Status | Notes | Examples |
+|---|---|---|---|---|
+| `add` | | ✅ | Plain add is supported. Any other flags aren't supported | |
+| `status` | | ✅ | | |
+| `commit` | | ✅ | | - [commit](_examples/commit/main.go) |
+| `reset` | | ✅ | | |
+| `rm` | | ✅ | | |
+| `mv` | | ✅ | | |
+
+## Branching and merging
+
+| Feature | Sub-feature | Status | Notes | Examples |
+|---|---|---|---|---|
+| `branch` | | ✅ | | - [branch](_examples/branch/main.go) |
+| `checkout` | | ✅ | Basic usages of checkout are supported. | - [checkout](_examples/checkout/main.go) |
+| `merge` | | ❌ | | |
+| `mergetool` | | ❌ | | |
+| `stash` | | ❌ | | |
+| `tag` | | ✅ | | - [tag](_examples/tag/main.go) <br/> - [tag create and push](_examples/tag-create-push/main.go) |
+
+## Sharing and updating projects
+
+| Feature | Sub-feature | Status | Notes | Examples |
+|---|---|---|---|---|
+| `fetch` | | ✅ | | |
+| `pull` | | ✅ | Only supports merges where the merge can be resolved as a fast-forward. | - [pull](_examples/pull/main.go) |
+| `push` | | ✅ | | - [push](_examples/push/main.go) |
+| `remote` | | ✅ | | - [remotes](_examples/remotes/main.go) |
+| `submodule` | | ✅ | | - [submodule](_examples/submodule/main.go) |
+| `submodule` | deinit | ❌ | | |
+
+## Inspection and comparison
+
+| Feature | Sub-feature | Status | Notes | Examples |
+|---|---|---|---|---|
+| `show` | | ✅ | | |
+| `log` | | ✅ | | - [log](_examples/log/main.go) |
+| `shortlog` | | (see log) | | |
+| `describe` | | ❌ | | |
+
+## Patching
+
+| Feature | Sub-feature | Status | Notes | Examples |
+|---|---|---|---|---|
+| `apply` | | ❌ | | |
+| `cherry-pick` | | ❌ | | |
+| `diff` | | ✅ | Patch object with UnifiedDiff output representation. | |
+| `rebase` | | ❌ | | |
+| `revert` | | ❌ | | |
+
+## Debugging
+
+| Feature | Sub-feature | Status | Notes | Examples |
+|---|---|---|---|---|
+| `bisect` | | ❌ | | |
+| `blame` | | ✅ | | - [blame](_examples/blame/main.go) |
+| `grep` | | ✅ | | |
+
+## Email
+
+| Feature | Sub-feature | Status | Notes | Examples |
+|---|---|---|---|---|
+| `am` | | ❌ | | |
+| `apply` | | ❌ | | |
+| `format-patch` | | ❌ | | |
+| `send-email` | | ❌ | | |
+| `request-pull` | | ❌ | | |
+
+## External systems
+
+| Feature | Sub-feature | Status | Notes | Examples |
+|---|---|---|---|---|
+| `svn` | | ❌ | | |
+| `fast-import` | | ❌ | | |
+| `lfs` | | ❌ | | |
+
+## Administration
+
+| Feature | Sub-feature | Status | Notes | Examples |
+|---|---|---|---|---|
+| `clean` | | ✅ | | |
+| `gc` | | ❌ | | |
+| `fsck` | | ❌ | | |
+| `reflog` | | ❌ | | |
+| `filter-branch` | | ❌ | | |
+| `instaweb` | | ❌ | | |
+| `archive` | | ❌ | | |
+| `bundle` | | ❌ | | |
+| `prune` | | ❌ | | |
+| `repack` | | ❌ | | |
+
+## Server admin
+
+| Feature | Sub-feature | Status | Notes | Examples |
+|---|---|---|---|---|
+| `daemon` | | ❌ | | |
+| `update-server-info` | | ❌ | | |
+
+## Advanced
+
+| Feature | Sub-feature | Status | Notes | Examples |
+|---|---|---|---|---|
+| `notes` | | ❌ | | |
+| `replace` | | ❌ | | |
+| `worktree` | | ❌ | | |
+| `annotate` | | (see blame) | | |
+
+## GPG
+
+| Feature | Sub-feature | Status | Notes | Examples |
+|---|---|---|---|---|
+| `git-verify-commit` | | ✅ | | |
+| `git-verify-tag` | | ✅ | | |
+
+## Plumbing commands
+
+| Feature | Sub-feature | Status | Notes | Examples |
+|---|---|---|---|---|
+| `cat-file` | | ✅ | | |
+| `check-ignore` | | ❌ | | |
+| `commit-tree` | | ❌ | | |
+| `count-objects` | | ❌ | | |
+| `diff-index` | | ❌ | | |
+| `for-each-ref` | | ✅ | | |
+| `hash-object` | | ✅ | | |
+| `ls-files` | | ✅ | | |
+| `ls-remote` | | ✅ | | - [ls-remote](_examples/ls-remote/main.go) |
+| `merge-base` | `--independent` <br/> `--is-ancestor` | ⚠️ (partial) | Calculates the merge-base only between two commits. | - [merge-base](_examples/merge_base/main.go) |
+| `merge-base` | `--fork-point` <br/> `--octopus` | ❌ | | |
+| `read-tree` | | ❌ | | |
+| `rev-list` | | ✅ | | |
+| `rev-parse` | | ❌ | | |
+| `show-ref` | | ✅ | | |
+| `symbolic-ref` | | ✅ | | |
+| `update-index` | | ❌ | | |
+| `update-ref` | | ❌ | | |
+| `verify-pack` | | ❌ | | |
+| `write-tree` | | ❌ | | |
+
+## Indexes and Git Protocols
+
+| Feature | Version | Status | Notes |
+|---|---|---|---|
+| index | [v1](https://github.com/git/git/blob/master/Documentation/gitformat-index.txt) | ❌ | |
+| index | [v2](https://github.com/git/git/blob/master/Documentation/gitformat-index.txt) | ✅ | |
+| index | [v3](https://github.com/git/git/blob/master/Documentation/gitformat-index.txt) | ❌ | |
+| pack-protocol | [v1](https://github.com/git/git/blob/master/Documentation/gitprotocol-pack.txt) | ✅ | |
+| pack-protocol | [v2](https://github.com/git/git/blob/master/Documentation/gitprotocol-v2.txt) | ❌ | |
+| multi-pack-index | [v1](https://github.com/git/git/blob/master/Documentation/gitformat-pack.txt) | ❌ | |
+| pack-*.rev files | [v1](https://github.com/git/git/blob/master/Documentation/gitformat-pack.txt) | ❌ | |
+| pack-*.mtimes files | [v1](https://github.com/git/git/blob/master/Documentation/gitformat-pack.txt) | ❌ | |
+| cruft packs | | ❌ | |
+
+## Capabilities
+
+| Feature | Status | Notes |
+|---|---|---|
+| `multi_ack` | ❌ | |
+| `multi_ack_detailed` | ❌ | |
+| `no-done` | ❌ | |
+| `thin-pack` | ❌ | |
+| `side-band` | ⚠️ (partial) | |
+| `side-band-64k` | ⚠️ (partial) | |
+| `ofs-delta` | ✅ | |
+| `agent` | ✅ | |
+| `object-format` | ❌ | |
+| `symref` | ✅ | |
+| `shallow` | ✅ | |
+| `deepen-since` | ✅ | |
+| `deepen-not` | ❌ | |
+| `deepen-relative` | ❌ | |
+| `no-progress` | ✅ | |
+| `include-tag` | ✅ | |
+| `report-status` | ✅ | |
+| `report-status-v2` | ❌ | |
+| `delete-refs` | ✅ | |
+| `quiet` | ❌ | |
+| `atomic` | ✅ | |
+| `push-options` | ✅ | |
+| `allow-tip-sha1-in-want` | ✅ | |
+| `allow-reachable-sha1-in-want` | ❌ | |
+| `push-cert=<nonce>` | ❌ | |
+| `filter` | ❌ | |
+| `session-id=<session id>` | ❌ | |
+
+## Transport Schemes
+
+| Scheme | Status | Notes | Examples |
+|---|---|---|---|
+| `http(s)://` (dumb)  | ❌ | | |
+| `http(s)://` (smart) | ✅ | | |
+| `git://`             | ✅ | | |
+| `ssh://`             | ✅ | | |
+| `file://`            | ⚠️ (partial) | Warning: this is not pure Golang. This shells out to the `git` binary. | |
+| Custom               | ✅ | All existing schemes can be replaced by custom implementations. | - [custom_http](_examples/custom_http/main.go) |
+
+## SHA256
+
+| Feature | Sub-feature | Status | Notes | Examples |
+|---|---|---|---|---|
+| `init` | | ✅ | Requires building with tag sha256. |  - [init](_examples/sha256/main.go) |
+| `commit` | | ✅ | Requires building with tag sha256. |  - [commit](_examples/sha256/main.go) |
+| `pull` | | ❌ | | |
+| `fetch` | | ❌ | | |
+| `push` | | ❌ | | |
+
+## Other features
+
+| Feature | Sub-feature | Status | Notes | Examples |
+|---|---|---|---|---|
+| `config` | `--local` | ✅  | Read and write per-repository (`.git/config`). | |
+| `config` | `--global` <br/> `--system` | ✅  | Read-only. | |
+| `gitignore` | | ✅ | | |
+| `gitattributes` | | ✅ | | |
+| `git-worktree` | | ❌ | Multiple worktrees are not supported. | |
diff --git a/EXTENDING.md b/EXTENDING.md
new file mode 100644
index 0000000..a2778e3
--- /dev/null
+++ b/EXTENDING.md
@@ -0,0 +1,78 @@
+# Extending go-git
+
+`go-git` was built in a highly extensible manner, which enables some of its functionalities to be changed or extended without the need of changing its codebase. Here are the key extensibility features:
+
+## Dot Git Storers
+
+Dot git storers are the components responsible for storing the Git internal files, including objects and references.
+
+The built-in storer implementations include [memory](storage/memory) and [filesystem](storage/filesystem). The `memory` storer stores all the data in memory, and its use look like this:
+
+```go
+	r, err := git.Init(memory.NewStorage(), nil)
+```
+
+The `filesystem` storer stores the data in the OS filesystem, and can be used as follows:
+
+```go
+    r, err := git.Init(filesystem.NewStorage(osfs.New("/tmp/foo")), nil)
+```
+
+New implementations can be created by implementing the [storage.Storer interface](storage/storer.go#L16).
+
+## Filesystem
+
+Git repository worktrees are managed using a filesystem abstraction based on [go-billy](https://github.com/go-git/go-billy). The Git operations will take place against the specific filesystem implementation. Initialising a repository in Memory can be done as follows:
+
+```go
+	fs := memfs.New()
+	r, err := git.Init(memory.NewStorage(), fs)
+```
+
+The same operation can be done against the OS filesystem:
+
+```go
+    fs := osfs.New("/tmp/foo")
+    r, err := git.Init(memory.NewStorage(), fs)
+```
+
+New filesystems (e.g. cloud based storage) could be created by implementing `go-billy`'s [Filesystem interface](https://github.com/go-git/go-billy/blob/326c59f064021b821a55371d57794fbfb86d4cb3/fs.go#L52).
+
+## Transport Schemes
+
+Git supports various transport schemes, including `http`, `https`, `ssh`, `git`, `file`. `go-git` defines the [transport.Transport interface](plumbing/transport/common.go#L48) to represent them.
+
+The built-in implementations can be replaced by calling `client.InstallProtocol`.
+
+An example of changing the built-in `https` implementation to skip TLS could look like this:
+
+```go
+	customClient := &http.Client{
+		Transport: &http.Transport{
+			TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
+		},
+	}
+
+	client.InstallProtocol("https", githttp.NewClient(customClient))
+```
+
+Some internal implementations enables code reuse amongst the different transport implementations. Some of these may be made public in the future (e.g. `plumbing/transport/internal/common`).
+
+## Cache
+
+Several different operations across `go-git` lean on caching of objects in order to achieve optimal performance. The caching functionality is defined by the [cache.Object interface](plumbing/cache/common.go#L17).
+
+Two built-in implementations are `cache.ObjectLRU` and `cache.BufferLRU`. However, the caching functionality can be customized by implementing the interface `cache.Object` interface.
+
+## Hash
+
+`go-git` uses the `crypto.Hash` interface to represent hash functions. The built-in implementations are `github.com/pjbgf/sha1cd` for SHA1 and Go's `crypto/SHA256`.
+
+The default hash functions can be changed by calling `hash.RegisterHash`.
+```go
+    func init() {
+        hash.RegisterHash(crypto.SHA1, sha1.New)
+    }
+```
+
+New `SHA1` or `SHA256` hash functions that implement the `hash.RegisterHash` interface can be registered by calling `RegisterHash`.
diff --git a/_examples/README.md b/_examples/README.md
index 1f150f9..46f1fb0 100644
--- a/_examples/README.md
+++ b/_examples/README.md
@@ -24,8 +24,12 @@ Here you can find a list of annotated _go-git_ examples:
 - [progress](progress/main.go) - Printing the progress information from the sideband.
 - [revision](revision/main.go) - Solve a revision into a commit.
 - [submodule](submodule/main.go) - Submodule update remote.
+- [azure devops](azure_devops/main.go) - Cloning Azure DevOps repositories.
+- [blame](blame/main.go) - Blame/annotate a commit.
+- [ls-remote](ls-remote/main.go) - List remote tags without cloning a repository.
 
 ### Advanced
 - [custom_http](custom_http/main.go) - Replacing the HTTP client using a custom one.
 - [clone with context](context/main.go) - Cloning a repository with graceful cancellation.
 - [storage](storage/README.md) - Implementing a custom storage system.
+- [sha256](sha256/main.go) - Init and commiting repositories that use sha256 as object format.