Merge pull request #860 from enverbisevac/master

add clone --shared feature

11 files changed, 353 insertions, 173 deletions

diff --git a/.gitignore b/.gitignore
index 361133d..b7f2c58 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,3 +4,4 @@ coverage.txt
 profile.out
 .tmp/
 .git-dist/
+.vscode
diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md
index afd4f03..bbffea5 100644
--- a/COMPATIBILITY.md
+++ b/COMPATIBILITY.md
@@ -5,229 +5,229 @@ 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) |
+| 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` <br/>`--shared` | ✅     |       | - [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` | | ✅ | | |
+| 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) |
+| 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 | ❌ | | |
+| 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` | | ❌ | | |
+| 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` | | ❌ | | |
+| 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                           |
+| -------- | ----------- | ------ | ----- | ---------------------------------- |
+| `bisect` |             | ❌     |       |                                    |
+| `blame`  |             | ✅     |       | - [blame](_examples/blame/main.go) |
+| `grep`   |             | ✅     |       |                                    |
 
 ## Email
 
-| Feature | Sub-feature | Status | Notes | Examples |
-|---|---|---|---|---|
-| `am` | | ❌ | | |
-| `apply` | | ❌ | | |
-| `format-patch` | | ❌ | | |
-| `send-email` | | ❌ | | |
-| `request-pull` | | ❌ | | |
+| 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` | | ❌ | | |
+| 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` | | ❌ | | |
+| 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` | | ❌ | | |
+| Feature              | Sub-feature | Status | Notes | Examples |
+| -------------------- | ----------- | ------ | ----- | -------- |
+| `daemon`             |             | ❌     |       |          |
+| `update-server-info` |             | ❌     |       |          |
 
 ## Advanced
 
-| Feature | Sub-feature | Status | Notes | Examples |
-|---|---|---|---|---|
-| `notes` | | ❌ | | |
-| `replace` | | ❌ | | |
-| `worktree` | | ❌ | | |
-| `annotate` | | (see blame) | | |
+| 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` | | ✅ | | |
+| 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` | | ❌ | | |
+| 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 | | ❌ | |
+| 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>` | ❌ | |
+| 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) |
+| 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` | | ❌ | | |
+| 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. | |
+| 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/options.go b/options.go
index c68bf2b..8902b7e 100644
--- a/options.go
+++ b/options.go
@@ -78,6 +78,15 @@ type CloneOptions struct {
 	CABundle []byte
 	// ProxyOptions provides info required for connecting to a proxy.
 	ProxyOptions transport.ProxyOptions
+	// When the repository to clone is on the local machine, instead of
+	// using hard links, automatically setup .git/objects/info/alternates
+	// to share the objects with the source repository.
+	// The resulting repository starts out without any object of its own.
+	// NOTE: this is a possibly dangerous operation; do not use it unless
+	// you understand what it does.
+	//
+	// [Reference]: https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---shared
+	Shared bool
 }
 
 // Validate validates the fields and sets the default values.
diff --git a/plumbing/storer/object.go b/plumbing/storer/object.go
index d8a9c27..126b374 100644
--- a/plumbing/storer/object.go
+++ b/plumbing/storer/object.go
@@ -42,6 +42,7 @@ type EncodedObjectStorer interface {
 	HasEncodedObject(plumbing.Hash) error
 	// EncodedObjectSize returns the plaintext size of the encoded object.
 	EncodedObjectSize(plumbing.Hash) (int64, error)
+	AddAlternate(remote string) error
 }
 
 // DeltaObjectStorer is an EncodedObjectStorer that can return delta
diff --git a/plumbing/storer/object_test.go b/plumbing/storer/object_test.go
index 30424ff..f2e6a5e 100644
--- a/plumbing/storer/object_test.go
+++ b/plumbing/storer/object_test.go
@@ -168,3 +168,7 @@ func (o *MockObjectStorage) IterEncodedObjects(t plumbing.ObjectType) (EncodedOb
 func (o *MockObjectStorage) Begin() Transaction {
 	return nil
 }
+
+func (o *MockObjectStorage) AddAlternate(remote string) error {
+	return nil
+}
diff --git a/repository.go b/repository.go
index 013b53f..4898838 100644
--- a/repository.go
+++ b/repository.go
@@ -22,6 +22,7 @@ import (
 	"github.com/go-git/go-git/v5/config"
 	"github.com/go-git/go-git/v5/internal/path_util"
 	"github.com/go-git/go-git/v5/internal/revision"
+	"github.com/go-git/go-git/v5/internal/url"
 	"github.com/go-git/go-git/v5/plumbing"
 	"github.com/go-git/go-git/v5/plumbing/cache"
 	formatcfg "github.com/go-git/go-git/v5/plumbing/format/config"
@@ -62,6 +63,7 @@ var (
 	ErrUnableToResolveCommit     = errors.New("unable to resolve commit")
 	ErrPackedObjectsNotSupported = errors.New("packed objects not supported")
 	ErrSHA256NotSupported        = errors.New("go-git was not compiled with SHA256 support")
+	ErrAlternatePathNotSupported = errors.New("alternate path must use the file scheme")
 )
 
 // Repository represents a git repository
@@ -887,6 +889,30 @@ func (r *Repository) clone(ctx context.Context, o *CloneOptions) error {
 		return err
 	}
 
+	// When the repository to clone is on the local machine,
+	// instead of using hard links, automatically setup .git/objects/info/alternates
+	// to share the objects with the source repository
+	if o.Shared {
+		if !url.IsLocalEndpoint(o.URL) {
+			return ErrAlternatePathNotSupported
+		}
+		altpath := o.URL
+		remoteRepo, err := PlainOpen(o.URL)
+		if err != nil {
+			return fmt.Errorf("failed to open remote repository: %w", err)
+		}
+		conf, err := remoteRepo.Config()
+		if err != nil {
+			return fmt.Errorf("failed to read remote repository configuration: %w", err)
+		}
+		if !conf.Core.IsBare {
+			altpath = path.Join(altpath, GitDirName)
+		}
+		if err := r.Storer.AddAlternate(altpath); err != nil {
+			return fmt.Errorf("failed to add alternate file to git objects dir: %w", err)
+		}
+	}
+
 	ref, err := r.fetchAndUpdateReferences(ctx, &FetchOptions{
 		RefSpecs:        c.Fetch,
 		Depth:           o.Depth,
diff --git a/repository_test.go b/repository_test.go
index 3154f1d..f6839b6 100644
--- a/repository_test.go
+++ b/repository_test.go
@@ -9,6 +9,7 @@ import (
 	"os"
 	"os/exec"
 	"os/user"
+	"path"
 	"path/filepath"
 	"regexp"
 	"strings"
@@ -791,6 +792,101 @@ func (s *RepositorySuite) TestPlainClone(c *C) {
 	c.Assert(cfg.Branches["master"].Name, Equals, "master")
 }
 
+func (s *RepositorySuite) TestPlainCloneBareAndShared(c *C) {
+	dir, clean := s.TemporalDir()
+	defer clean()
+
+	remote := s.GetBasicLocalRepositoryURL()
+
+	r, err := PlainClone(dir, true, &CloneOptions{
+		URL:    remote,
+		Shared: true,
+	})
+	c.Assert(err, IsNil)
+
+	altpath := path.Join(dir, "objects", "info", "alternates")
+	_, err = os.Stat(altpath)
+	c.Assert(err, IsNil)
+
+	data, err := os.ReadFile(altpath)
+	c.Assert(err, IsNil)
+
+	line := path.Join(remote, GitDirName, "objects") + "\n"
+	c.Assert(string(data), Equals, line)
+
+	cfg, err := r.Config()
+	c.Assert(err, IsNil)
+	c.Assert(cfg.Branches, HasLen, 1)
+	c.Assert(cfg.Branches["master"].Name, Equals, "master")
+}
+
+func (s *RepositorySuite) TestPlainCloneShared(c *C) {
+	dir, clean := s.TemporalDir()
+	defer clean()
+
+	remote := s.GetBasicLocalRepositoryURL()
+
+	r, err := PlainClone(dir, false, &CloneOptions{
+		URL:    remote,
+		Shared: true,
+	})
+	c.Assert(err, IsNil)
+
+	altpath := path.Join(dir, GitDirName, "objects", "info", "alternates")
+	_, err = os.Stat(altpath)
+	c.Assert(err, IsNil)
+
+	data, err := os.ReadFile(altpath)
+	c.Assert(err, IsNil)
+
+	line := path.Join(remote, GitDirName, "objects") + "\n"
+	c.Assert(string(data), Equals, line)
+
+	cfg, err := r.Config()
+	c.Assert(err, IsNil)
+	c.Assert(cfg.Branches, HasLen, 1)
+	c.Assert(cfg.Branches["master"].Name, Equals, "master")
+}
+
+func (s *RepositorySuite) TestPlainCloneSharedHttpShouldReturnError(c *C) {
+	dir, clean := s.TemporalDir()
+	defer clean()
+
+	remote := "http://somerepo"
+
+	_, err := PlainClone(dir, false, &CloneOptions{
+		URL:    remote,
+		Shared: true,
+	})
+	c.Assert(err, Equals, ErrAlternatePathNotSupported)
+}
+
+func (s *RepositorySuite) TestPlainCloneSharedHttpsShouldReturnError(c *C) {
+	dir, clean := s.TemporalDir()
+	defer clean()
+
+	remote := "https://somerepo"
+
+	_, err := PlainClone(dir, false, &CloneOptions{
+		URL:    remote,
+		Shared: true,
+	})
+	c.Assert(err, Equals, ErrAlternatePathNotSupported)
+}
+
+func (s *RepositorySuite) TestPlainCloneSharedSSHShouldReturnError(c *C) {
+	dir, clean := s.TemporalDir()
+	defer clean()
+
+	remote := "ssh://somerepo"
+
+	_, err := PlainClone(dir, false, &CloneOptions{
+		URL:    remote,
+		Shared: true,
+	})
+	c.Assert(err, Equals, ErrAlternatePathNotSupported)
+}
+
 func (s *RepositorySuite) TestPlainCloneWithRemoteName(c *C) {
 	dir, clean := s.TemporalDir()
 	defer clean()
diff --git a/storage/filesystem/dotgit/dotgit.go b/storage/filesystem/dotgit/dotgit.go
index e02e6dd..3080e4a 100644
--- a/storage/filesystem/dotgit/dotgit.go
+++ b/storage/filesystem/dotgit/dotgit.go
@@ -8,7 +8,9 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"path"
 	"path/filepath"
+	"runtime"
 	"sort"
 	"strings"
 	"time"
@@ -38,6 +40,7 @@ const (
 	remotesPath    = "remotes"
 	logsPath       = "logs"
 	worktreesPath  = "worktrees"
+	alternatesPath = "alternates"
 
 	tmpPackedRefsPrefix = "._packed-refs"
 
@@ -1105,10 +1108,38 @@ func (d *DotGit) Module(name string) (billy.Filesystem, error) {
 	return d.fs.Chroot(d.fs.Join(modulePath, name))
 }
 
+func (d *DotGit) AddAlternate(remote string) error {
+	altpath := d.fs.Join(objectsPath, infoPath, alternatesPath)
+
+	f, err := d.fs.OpenFile(altpath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0640)
+	if err != nil {
+		return fmt.Errorf("cannot open file: %w", err)
+	}
+	defer f.Close()
+
+	// locking in windows throws an error, based on comments
+	// https://github.com/go-git/go-git/pull/860#issuecomment-1751823044
+	// do not lock on windows platform.
+	if runtime.GOOS != "windows" {
+		if err = f.Lock(); err != nil {
+			return fmt.Errorf("cannot lock file: %w", err)
+		}
+		defer f.Unlock()
+	}
+
+	line := path.Join(remote, objectsPath) + "\n"
+	_, err = io.WriteString(f, line)
+	if err != nil {
+		return fmt.Errorf("error writing 'alternates' file: %w", err)
+	}
+
+	return nil
+}
+
 // Alternates returns DotGit(s) based off paths in objects/info/alternates if
 // available. This can be used to checks if it's a shared repository.
 func (d *DotGit) Alternates() ([]*DotGit, error) {
-	altpath := d.fs.Join("objects", "info", "alternates")
+	altpath := d.fs.Join(objectsPath, infoPath, alternatesPath)
 	f, err := d.fs.Open(altpath)
 	if err != nil {
 		return nil, err
diff --git a/storage/filesystem/storage.go b/storage/filesystem/storage.go
index 7e7a2c5..2069d3a 100644
--- a/storage/filesystem/storage.go
+++ b/storage/filesystem/storage.go
@@ -74,3 +74,7 @@ func (s *Storage) Filesystem() billy.Filesystem {
 func (s *Storage) Init() error {
 	return s.dir.Initialize()
 }
+
+func (s *Storage) AddAlternate(remote string) error {
+	return s.dir.AddAlternate(remote)
+}
diff --git a/storage/memory/storage.go b/storage/memory/storage.go
index ef6a445..79211c7 100644
--- a/storage/memory/storage.go
+++ b/storage/memory/storage.go
@@ -202,6 +202,10 @@ func (o *ObjectStorage) DeleteLooseObject(plumbing.Hash) error {
 	return errNotSupported
 }
 
+func (o *ObjectStorage) AddAlternate(remote string) error {
+	return errNotSupported
+}
+
 type TxObjectStorage struct {
 	Storage *ObjectStorage
 	Objects map[plumbing.Hash]plumbing.EncodedObject
diff --git a/storage/transactional/object.go b/storage/transactional/object.go
index 5d102b0..b43c96d 100644
--- a/storage/transactional/object.go
+++ b/storage/transactional/object.go
@@ -82,3 +82,7 @@ func (o *ObjectStorage) Commit() error {
 		return err
 	})
 }
+
+func (o *ObjectStorage) AddAlternate(remote string) error {
+	return o.temporal.AddAlternate(remote)
+}