Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #804 from pjbgf/docs
*: Improve docs on examples, compatibility and extensibility
- Loading branch information
Showing
3 changed files
with
315 additions
and
111 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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` | | ✅ | | | | ||
|
||
|
||
| 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. | | |
Oops, something went wrong.