Skip to content

Commit 125b671

Browse files
pjbgfpjbgf
committed
Initial version of go-git docs
Signed-off-by: Paulo Gomes <[email protected]>
1 parent 956f3a6 commit 125b671

11 files changed

+415
-0
lines changed

‎.github/workflows/gh-pages.yml

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
name: publish-docs
2+
on:
3+
push:
4+
branches:
5+
- main
6+
7+
permissions:
8+
contents: write
9+
10+
jobs:
11+
deploy:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- uses: actions/checkout@v4
15+
- name: Configure Git Credentials
16+
run: |
17+
git config user.name github-actions[bot]
18+
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
19+
- uses: actions/setup-python@v5
20+
with:
21+
python-version: 3.x
22+
23+
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
24+
- uses: actions/cache@v4
25+
with:
26+
key: "mkdocs-material-${{ env.cache_id }}"
27+
path: .cache
28+
restore-keys: |
29+
mkdocs-material-
30+
31+
- run: pip install mkdocs-material
32+
- run: mkdocs gh-deploy --force

‎Makefile

Whitespace-only changes.

‎README.md

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# go-git Docs
2+
3+
This repository contains the documentation for [github.com/go-git/go-git](https://github.com/go-git/go-git).
4+
5+
## Contributing
6+
7+
Contributions are welcome! Feel free to submit pull requests to improve or expand the documentation. When contributing:
8+
9+
1. Fork the repository
10+
2. Create your feature branch (`git checkout -b feature/improvement`)
11+
3. Commit your changes (`git commit -am 'Add some improvement'`)
12+
4. Push to the branch (`git push origin feature/improvement`)
13+
5. Create a Pull Request
14+
15+
## License
16+
17+
Licensed under the Apache License, Version 2.0 (the "License");
18+
you may not use this file except in compliance with the License.
19+
You may obtain a copy of the License at
20+
21+
http://www.apache.org/licenses/LICENSE-2.0
22+
23+
Unless required by applicable law or agreed to in writing, software
24+
distributed under the License is distributed on an "AS IS" BASIS,
25+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
26+
See the License for the specific language governing permissions and
27+
limitations under the License.

‎mkdocs.yml

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
site_name: go-git Documentation
2+
site_url: https://go-git.github.io/docs
3+
repo_url: https://github.com/go-git/docs
4+
5+
theme:
6+
name: readthedocs
7+
highlightjs: true
8+
hljs_languages:
9+
- go
10+
11+
docs_dir: src
12+
13+
markdown_extensions:
14+
- pymdownx.superfences
15+
- pymdownx.tabbed:
16+
alternate_style: true
17+
18+
nav:
19+
- Home: index.md
20+
- Tutorials:
21+
- Getting Started: tutorials/getting-started.md
22+
- Advanced Usage: tutorials/advanced-usage.md
23+
- Troubleshooting: tutorials/troubleshooting.md
24+
- Migrating to V6: tutorials/migrating-from-v5-to-v6.md
25+
- Concepts:
26+
- Overview: concepts/overview.md

‎src/concepts/overview.md

+96
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
layout: default
3+
title: Concepts
4+
---
5+
# Concepts
6+
7+
`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.
8+
9+
Here are key concepts that enable that extensibility:
10+
11+
## Dot Git Storers
12+
13+
Dot git storers are the components responsible for storing the Git internal files, including objects and references.
14+
15+
The built-in storer implementations include [memory] and [filesystem]. The `memory` storer stores all the data in memory, and its use look like this:
16+
17+
```go
18+
r, err := git.Init(memory.NewStorage(), nil)
19+
```
20+
21+
The `filesystem` storer stores the data in the OS filesystem, and can be used as follows:
22+
23+
```go
24+
r, err := git.Init(filesystem.NewStorage(osfs.New("/tmp/foo")), nil)
25+
```
26+
27+
New implementations can be created by implementing the [storage.Storer interface].
28+
29+
[memory]: https://github.com/go-git/go-git/tree/main/storage/memory
30+
[filesystem]: https://github.com/go-git/go-git/tree/main/storage/filesystem
31+
[storage.Storer interface]: https://github.com/go-git/go-git/tree/main/storage/storer.go#L16
32+
33+
## Filesystem
34+
35+
Git repository worktrees are managed using a filesystem abstraction based on [go-billy]. The Git operations will take place against the specific filesystem implementation. Initialising a repository in Memory can be done as follows:
36+
37+
```go
38+
fs := memfs.New()
39+
r, err := git.Init(memory.NewStorage(), fs)
40+
```
41+
42+
The same operation can be done against the OS filesystem:
43+
44+
```go
45+
fs := osfs.New("/tmp/foo")
46+
r, err := git.Init(memory.NewStorage(), fs)
47+
```
48+
49+
New filesystems (e.g. cloud based storage) could be created by implementing `go-billy`'s [Filesystem interface].
50+
51+
[go-billy]: https://github.com/go-git/go-billy
52+
[Filesystem interface]: https://github.com/go-git/go-billy/blob/326c59f064021b821a55371d57794fbfb86d4cb3/fs.go#L52
53+
54+
## Transport Schemes
55+
56+
Git supports various transport schemes, including `http`, `https`, `ssh`, `git`, `file`. `go-git` defines the [transport.Transport interface] to represent them.
57+
58+
The built-in implementations can be replaced by calling `transport.Register`.
59+
60+
An example of changing the built-in `https` implementation to skip TLS could look like this:
61+
62+
```go
63+
customClient := &http.Client{
64+
Transport: &http.Transport{
65+
TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
66+
},
67+
}
68+
69+
transport.Register("https", githttp.NewClient(customClient))
70+
```
71+
72+
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`).
73+
74+
[transport.Transport interface]: https://github.com/go-git/go-git/tree/main/plumbing/transport/common.go#L48
75+
76+
## Cache
77+
78+
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].
79+
80+
Two built-in implementations are `cache.ObjectLRU` and `cache.BufferLRU`. However, the caching functionality can be customized by implementing the interface `cache.Object` interface.
81+
82+
[cache.Object interface]: https://github.com/go-git/go-git/tree/main/plumbing/cache/common.go#L17
83+
84+
## Hash
85+
86+
`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`.
87+
88+
The default hash functions can be changed by calling `hash.RegisterHash`.
89+
```go
90+
func init() {
91+
hash.RegisterHash(crypto.SHA1, sha1.New)
92+
}
93+
```
94+
95+
New `SHA1` or `SHA256` hash functions that implement the `hash.RegisterHash` interface can be registered by calling `RegisterHash`.
96+

‎src/index.md

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
layout: default
3+
title: go-git Documentation
4+
---
5+
6+
# go-git Documentation
7+
8+
go-git is a highly extensible Git implementation in pure Go. This documentation will help you understand and use go-git effectively in your projects.
9+
10+
**Warning:** This documentation targets the v6 version of go-git. APIs are subject to change until v6 is officially released.
11+
12+
## Quick Start
13+
14+
```go
15+
import (
16+
"github.com/go-git/go-git/v5"
17+
)
18+
19+
func main() {
20+
// Clone repository
21+
repo, err := git.PlainClone("/path/to/repo", false, &git.CloneOptions{
22+
URL: "https://github.com/go-git/go-git",
23+
})
24+
}
25+
```
26+
27+
## Basic Concepts
28+
29+
For a detailed explanation of go-git's architecture, please refer to our [Architecture document](docs/concepts/architecture.md).

‎src/requirements.txt

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
mkdocs~=1.6.1

‎src/tutorials/advanced-usage.md

+109
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
layout: default
3+
title: Advanced Usage of go-git
4+
---
5+
# Advanced Usage of go-git
6+
7+
This guide covers advanced usage patterns and performance considerations
8+
when working with go-git.
9+
10+
## Performance Optimizations
11+
12+
When working with large repositories or performing intensive operations,
13+
consider the following performance tips:
14+
15+
### Reduce the amount of data being cloned
16+
- Shallow clones with setting depth to 1.
17+
- Use Sparse Checkout for only representing part of the repository tree
18+
in the Worktree.
19+
- When no tags are required, use `git.NoTags`. This will skip the cloning
20+
of tags, and all the objects they point to - which may result in a
21+
significant increase in cloned data.
22+
23+
### Storage Optimization
24+
- The fastest storage is the memory storage. For very large repositories
25+
make sure there is enough memory available. Used in conjunction with the
26+
filter option can lead to super efficient operations.
27+
28+
### SHA1
29+
- By default, go-git uses `github.com/pjbgf/sha1cd` as the SHA1 algorithm.
30+
It introduces collision detection, which results in slower performance.
31+
When only trustworthy servers are used, consider using the native SHA1
32+
implementation with `hash.RegisterHash(sha1.New())`.
33+
34+
## In-memory repositories
35+
36+
### Clone in between repositories held in memory
37+
38+
Here's an example of using a memfs filesystem, which can be used for multiple
39+
repositories. In this case, it can also be used to clone in-between sub-memfs
40+
filesystems which in fact reside on a higher level memfs.
41+
42+
```go
43+
var wg sync.WaitGroup
44+
45+
// /
46+
// /target
47+
// /src
48+
// /go-git
49+
// /go-billy
50+
func main() {
51+
rootfs := memfs.New()
52+
target, _ := rootfs.Chroot("/target")
53+
src, _ := rootfs.Chroot("/src")
54+
master, _ := src.Chroot("/go-git-master")
55+
concurrency, _ := src.Chroot("/go-git-concurrency")
56+
57+
wg.Add(2)
58+
// providing a thread-safe memfs enables running the below as go routines
59+
clone(master, "https://github.com/go-git/go-git", "master")
60+
clone(concurrency, "https://github.com/go-git/go-git", "read-concurrency")
61+
wg.Wait()
62+
63+
loader := server.NewFilesystemLoader(rootfs)
64+
client.InstallProtocol("file", server.NewClient(loader))
65+
66+
url := "file:///src/go-git-master"
67+
68+
dot, err := target.Chroot(".git")
69+
CheckIfError(err)
70+
71+
Info("git clone %s", url)
72+
storer := filesystem.NewStorage(dot, cache.NewObjectLRUDefault())
73+
r, err := git.Clone(storer, target, &git.CloneOptions{
74+
URL: url,
75+
})
76+
CheckIfError(err)
77+
78+
ref, err := r.Head()
79+
CheckIfError(err)
80+
81+
commit, err := r.CommitObject(ref.Hash())
82+
CheckIfError(err)
83+
84+
fmt.Println(commit)
85+
86+
url2 := "file:///src/go-git-concurrency"
87+
err = r.Fetch(&git.FetchOptions{
88+
RemoteURL: url2,
89+
RefSpecs: []config.RefSpec{
90+
...
91+
},
92+
})
93+
CheckIfError(err)
94+
}
95+
96+
func clone(fs billy.Filesystem, url, branch string) {
97+
storer := filesystem.NewStorage(fs, cache.NewObjectLRUDefault())
98+
99+
_, err := git.Clone(storer, nil, &git.CloneOptions{
100+
URL: url,
101+
SingleBranch: true,
102+
ReferenceName: plumbing.NewBranchReferenceName(branch),
103+
})
104+
wg.Done()
105+
106+
CheckIfError(err)
107+
fmt.Printf("Clone %q from %q: DONE\n", branch, url)
108+
}
109+
```

‎src/tutorials/getting-started.md

+50
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
layout: default
3+
title: Getting Started with go-git
4+
---
5+
# Getting Started with go-git
6+
7+
This guide demonstrates common Git operations using the go-git library.
8+
9+
The [go-git repository] contains many examples of how to do various
10+
operations using the latest version of go-git.
11+
12+
[go-git repository]: https://github.com/go-git/go-git/tree/main/_examples
13+
14+
## Cloning a Repository
15+
16+
The following example shows how to clone a Git repository to your local filesystem:
17+
18+
```go
19+
r, err := git.PlainClone("/path/to/repo", false, &git.CloneOptions{
20+
URL: "https://github.com/go-git/go-git",
21+
})
22+
```
23+
24+
## In-memory operations
25+
26+
The go-git library supports in-memory Git operations, which can be useful
27+
for faster cloning operations without touching the filesystem.
28+
29+
Here's how to clone a repository into memory:
30+
31+
### "With worktree"
32+
33+
```go
34+
wt := memfs.New()
35+
storer := memory.NewStorage()
36+
r, err := git.Clone(storer, wt, &git.CloneOptions{
37+
URL: "https://github.com/go-git/go-git",
38+
})
39+
```
40+
41+
### "Bare clone"
42+
43+
```go
44+
storer := memory.NewStorage()
45+
r, err := git.Clone(storer, nil, &git.CloneOptions{
46+
URL: "https://github.com/go-git/go-git",
47+
})
48+
```
49+
50+
For bare clones, the `Worktree` parameter should be set to `nil`.

0 commit comments

Comments
 (0)