Skip to content

Commit 22c9a4b

Browse files
retr0hretr0h
committed
chore: prepare for v2.1.1 release
1 parent 13f6d6b commit 22c9a4b

File tree

8 files changed

+357
-0
lines changed

8 files changed

+357
-0
lines changed

‎docs/versioned_docs/version-2.1.1/configuration.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
5+
# Configuration
6+
7+
Gilt uses [Viper][] to load configuation through multpile methods.
8+
9+
## Config File
10+
11+
Create the giltfile (`Giltfile.yaml`).
12+
13+
Clone the specified `url`@`version` to the configurable path `--gilt-dir`.
14+
Extract the repo the `dstDir` when `dstDir` is provided. Otherwise, copy files
15+
and/or directories to the desired destinations.
16+
17+
```yaml
18+
---
19+
giltDir: ~/.gilt/clone
20+
debug: false
21+
repositories:
22+
- git: https://github.com/retr0h/ansible-etcd.git
23+
version: 77a95b7
24+
dstDir: roles/retr0h.ansible-etcd
25+
- git: https://github.com/retr0h/ansible-etcd.git
26+
version: 1.1
27+
dstDir: roles/retr0h.ansible-etcd-tag
28+
- git: https://github.com/lorin/openstack-ansible-modules.git
29+
version: 2677cc3
30+
sources:
31+
- src: '*_manage'
32+
dstDir: library
33+
- src: nova_quota
34+
dstDir: library
35+
- src: neutron_router
36+
dstFile: library/neutron_router.py
37+
- src: tests
38+
dstDir: tests
39+
commands:
40+
- cmd: ansible-playbook
41+
args:
42+
- -i,
43+
- playbook.yml
44+
- cmd: bash
45+
args:
46+
- -c
47+
- who | grep tty
48+
```
49+
50+
## Env Vars
51+
52+
The config file can be overriden/defined through env vars.
53+
54+
```bash
55+
GILT_GILTFILE=Giltfile.yaml \
56+
GILT_GILTDIR=~/.gilt/clone \
57+
GILT_DEBUG=false \
58+
gilt overlay
59+
```
60+
61+
## Command Flags
62+
63+
The config file and/or env vars can be overriden/defined through cli flags.
64+
65+
```bash
66+
gilt \
67+
--gilt-file=Giltfile.yaml \
68+
--gilt-dir=~/.gilt/clone \
69+
--debug \
70+
overlay
71+
```
72+
73+
<!-- prettier-ignore-start -->
74+
[Viper]: https://github.com/spf13/viper
75+
<!-- prettier-ignore-end -->

‎docs/versioned_docs/version-2.1.1/contributing.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
sidebar_position: 6
3+
---
4+
5+
# Contributing
6+
7+
Contributions to Gilt are very welcome, but we ask that you read this document
8+
before submitting a PR.
9+
10+
:::note
11+
12+
This document applies to the [Gilt][] repository.
13+
14+
:::
15+
16+
## Before you start
17+
18+
- **Check existing work** - Is there an existing PR? Are there issues discussing
19+
the feature/change you want to make? Please make sure you consider/address
20+
these discussions in your work.
21+
- **Backwards compatibility** - Will your change break existing Giltfiles? It is
22+
much more likely that your change will merged if it backwards compatible. Is
23+
there an approach you can take that maintains this compatibility? If not,
24+
consider opening an issue first so that API changes can be discussed before
25+
you invest your time into a PR.
26+
27+
## 1. Setup
28+
29+
- **Go** - Gilt is written in [Go][]. We always support the latest two major Go
30+
versions, so make sure your version is recent enough.
31+
- **Node.js** - [Node.js][] is used to host Gilt's documentation server and is
32+
required if you want to run this server locally.
33+
34+
## 2. Making changes
35+
36+
- **Code style** - Try to maintain the existing code style where possible. Go
37+
code should be formatted by [`gofumpt`][gofumpt] and linted using
38+
[`golangci-lint`][golangci-lint]. Any Markdown or TypeScript files should be
39+
formatted and linted by [Prettier][]. This style is enforced by our CI to
40+
ensure that we have a consistent style across the project. You can use the
41+
`task fmt:check` command to lint the code locally and the `task fmt` command
42+
to automatically fix any issues that are found.
43+
- **Documentation** - Ensure that you add/update any relevant documentation. See
44+
the [updating documentation](#updating-documentation) section below.
45+
- **Tests** - Ensure that you add/update any relevant tests and that all tests
46+
are passing before submitting the PR. See the [writing tests](#writing-tests)
47+
section below.
48+
49+
### Running your changes
50+
51+
To run Gilt with working changes, you can use `go run main.go overlay`.
52+
53+
### Updating documentation
54+
55+
Gilt uses [Docusaurus][] to host a documentation server. The code for this is
56+
located in the Gilt repository. This can be setup and run locally by using
57+
`task docs:start` (requires `nodejs` & `yarn`). All content is written in
58+
Markdown and is located in the `docs/docs` directory. All Markdown documents
59+
should have an 80 character line wrap limit (enforced by Prettier).
60+
61+
### Writing tests
62+
63+
When making a changes, consider whether new tests are required. These tests
64+
should ensure that the functionality you are adding will continue to work in the
65+
future. Existing tests may also need updating if you have changed Gilt's
66+
behavior.
67+
68+
You may also consider adding unit tests for any new functions you have added.
69+
The unit tests should follow the Go convention of being location in a file named
70+
`*_test.go` in the same package as the code being tested.
71+
72+
Integration tests are located in the `tests` directory and executed by [Bats][].
73+
74+
## 3. Committing your code
75+
76+
Try to write meaningful commit messages and avoid having too many commits on the
77+
PR. Most PRs should likely have a single commit (although for bigger PRs it may
78+
be reasonable to split it in a few). Git squash and rebase is your friend!
79+
80+
If you're not sure how to format your commit message, check out [Conventional
81+
Commits][]. This style is enforced, and is a good way to make your commit
82+
messages more readable and consistent.
83+
84+
## 4. Submitting a PR
85+
86+
- **Describe your changes** - Ensure that you provide a comprehensive
87+
description of your changes.
88+
- **Issue/PR links** - Link any previous work such as related issues or PRs.
89+
Please describe how your changes differ to/extend this work.
90+
- **Examples** - Add any examples or screenshots that you think are useful to
91+
demonstrate the effect of your changes.
92+
- **Draft PRs** - If your changes are incomplete, but you would like to discuss
93+
them, open the PR as a draft and add a comment to start a discussion. Using
94+
comments rather than the PR description allows the description to be updated
95+
later while preserving any discussions.
96+
97+
## FAQ
98+
99+
> I want to contribute, where do I start?
100+
101+
All kinds of contributions are welcome, whether its a typo fix or a shiny new
102+
feature. You can also contribute by upvoting/commenting on issues or helping to
103+
answer questions.
104+
105+
> I'm stuck, where can I get help?
106+
107+
If you have questions, feel free open a [Discussion][] on GitHub.
108+
109+
<!-- prettier-ignore-start -->
110+
[Gilt]: https://github.com/retr0h/gilt
111+
[Go]: https://go.dev
112+
[Node.js]: https://nodejs.org/en/
113+
[gofumpt]: https://github.com/mvdan/gofumpt
114+
[golangci-lint]: https://golangci-lint.run
115+
[Prettier]: https://prettier.io/
116+
[Docusaurus]: https://docusaurus.io
117+
[Discussion]: https://github.com/retr0h/gilt/discussions
118+
[Conventional Commits]: https://www.conventionalcommits.org
119+
[Bats]: https://github.com/bats-core/bats-core
120+
<!-- prettier-ignore-end -->

‎docs/versioned_docs/version-2.1.1/installation.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# Installation
6+
7+
## Homebrew Tap
8+
9+
```bash
10+
brew install retr0h/tap/gilt
11+
```
12+
13+
## Go Install
14+
15+
```bash
16+
go install github.com/retr0h/gilt@latest
17+
```
18+
19+
## Python
20+
21+
```bash
22+
pip3 install python-gilt
23+
```

‎docs/versioned_docs/version-2.1.1/intro.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
slug: /
3+
sidebar_position: 1
4+
title: Home
5+
---
6+
7+
# Gilt
8+
9+
<img src="img/gilt.png" align="left" width="250px" height="250px" />
10+
11+
Gilt is a tool which aims to make repo management, manageable. Gilt clones
12+
repositories at a particular version, then overlays the repository to the
13+
provided destination. An alternate approach to "vendoring".
14+
15+
What makes Gilt interesting, is the ability to overlay particular files and/or
16+
directories from the specified repository to given destinations. Originally,
17+
this was quite helpful for those using Ansible, since libraries, plugins, and
18+
playbooks are often shared, but Ansible's [Galaxy][] has no mechanism to handle
19+
this. Currently, this is proving useful for overlaying [Helm charts][].
20+
21+
<br clear="left"/>
22+
23+
## Alternatives
24+
25+
- [Repo][]
26+
- [Git submodules][]
27+
- [Git subtree][]
28+
29+
## History
30+
31+
This project is a golang port of [Gilt][py-gilt], and aims to correct poor
32+
decisions made in the python version, primarially around config syntax,
33+
portability, and reproducibility.
34+
35+
<!-- prettier-ignore-start -->
36+
[Galaxy]: https://docs.ansible.com/ansible/latest/reference_appendices/galaxy.html
37+
[Helm charts]: https://helm.sh/docs/topics/charts/
38+
[Repo]: https://gerrit.googlesource.com/git-repo/+/refs/heads/master/README.md
39+
[Git submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
40+
[Git subtree]: https://github.com/git/git/blob/master/contrib/subtree/git-subtree.txt
41+
[py-gilt]: http://gilt.readthedocs.io/en/latest/
42+
<!-- prettier-ignore-end -->

‎docs/versioned_docs/version-2.1.1/testing.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
sidebar_position: 5
3+
---
4+
5+
# Testing
6+
7+
Check installed dependencies:
8+
9+
```bash
10+
task deps:check
11+
```
12+
13+
To execute tests:
14+
15+
```bash
16+
task test
17+
```
18+
19+
Auto format code:
20+
21+
```bash
22+
task fmt
23+
```
24+
25+
List helpful targets:
26+
27+
```bash
28+
task
29+
```

‎docs/versioned_docs/version-2.1.1/usage.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
sidebar_position: 4
3+
---
4+
5+
# Usage
6+
7+
## CLI
8+
9+
### Init Configuration
10+
11+
Initializes config file in the shell's current working directory:
12+
13+
```bash
14+
gilt init
15+
```
16+
17+
### Overlay Repository
18+
19+
Overlay a remote repository into the destination provided.
20+
21+
```bash
22+
gilt overlay
23+
```
24+
25+
### Debug
26+
27+
Display the git commands being executed.
28+
29+
```bash
30+
gilt --debug overlay
31+
```
32+
33+
## Package
34+
35+
### Overlay Repository
36+
37+
See example client in `examples/go-client/`.
38+
39+
```go
40+
func main() {
41+
debug := true
42+
logger := getLogger(debug)
43+
44+
c := config.Repositories{
45+
Debug: debug,
46+
GiltDir: "~/.gilt",
47+
Repositories: []config.Repository{
48+
{
49+
Git: "https://github.com/retr0h/ansible-etcd.git",
50+
Version: "77a95b7",
51+
DstDir: "../tmp/retr0h.ansible-etcd",
52+
},
53+
},
54+
}
55+
56+
var r repositoriesManager = repositories.New(c, logger)
57+
r.Overlay()
58+
}
59+
```

‎docs/versioned_sidebars/version-2.1.1-sidebars.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"docsSidebar": [
3+
{
4+
"type": "autogenerated",
5+
"dirName": "."
6+
}
7+
]
8+
}

‎docs/versions.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
[
2+
"2.1.1",
23
"2.1",
34
"2.0.3",
45
"2.0.2",

0 commit comments

Comments
 (0)