From 2f97d84ccc79c8e4f7fe431eacca0ccbf9d7358e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Mon, 1 Jul 2024 16:50:50 -0700 Subject: [PATCH] chore: prepare for v2.2.3 release --- .../version-2.2.3/configuration.md | 280 ++++++++++++++++++ .../version-2.2.3/contributing.md | 120 ++++++++ .../version-2.2.3/installation.md | 23 ++ docs/versioned_docs/version-2.2.3/intro.md | 42 +++ docs/versioned_docs/version-2.2.3/testing.md | 29 ++ docs/versioned_docs/version-2.2.3/usage.md | 67 +++++ .../version-2.2.3-sidebars.json | 8 + docs/versions.json | 1 + 8 files changed, 570 insertions(+) create mode 100644 docs/versioned_docs/version-2.2.3/configuration.md create mode 100644 docs/versioned_docs/version-2.2.3/contributing.md create mode 100644 docs/versioned_docs/version-2.2.3/installation.md create mode 100644 docs/versioned_docs/version-2.2.3/intro.md create mode 100644 docs/versioned_docs/version-2.2.3/testing.md create mode 100644 docs/versioned_docs/version-2.2.3/usage.md create mode 100644 docs/versioned_sidebars/version-2.2.3-sidebars.json diff --git a/docs/versioned_docs/version-2.2.3/configuration.md b/docs/versioned_docs/version-2.2.3/configuration.md new file mode 100644 index 0000000..13ac849 --- /dev/null +++ b/docs/versioned_docs/version-2.2.3/configuration.md @@ -0,0 +1,280 @@ +--- +sidebar_position: 3 +--- + +# Configuration + +Gilt uses [Viper][] to load configuation through multpile methods. + +## Config File + +Create the giltfile (`Giltfile.yaml`). + +Clone the specified `url`@`version` to the configurable path `--gilt-dir`. +Extract the repo the `dstDir` when `dstDir` is provided. Otherwise, copy files +and/or directories to the desired destinations. + +```yaml +--- +giltDir: ~/.gilt/clone +debug: false +parallel: true +repositories: + - git: https://github.com/retr0h/ansible-etcd.git + version: 77a95b7 + dstDir: roles/retr0h.ansible-etcd + - git: https://github.com/retr0h/ansible-etcd.git + version: 1.1 + dstDir: roles/retr0h.ansible-etcd-tag + - git: https://github.com/lorin/openstack-ansible-modules.git + version: 2677cc3 + sources: + - src: '*_manage' + dstDir: library + - src: nova_quota + dstDir: library + - src: neutron_router + dstFile: library/neutron_router.py + - src: tests + dstDir: tests + commands: + - cmd: ansible-playbook + args: + - -i, + - playbook.yml + - cmd: bash + args: + - -c + - who | grep tty +``` + +### Configuration Options + +#### `debug` + +- Type: boolean +- Default: `false` +- Required: no + +Enable / disable debug output + +#### `parallel` + +- Type: boolean +- Default: `true` +- Required: no + +Enable / disable fetching clones concurrently. The default is to fetch clones in +parallel, with one fetch per CPU, and a maximum of 8 concurrent processes. +Setting `parallel: false` will cause Gilt to fetch each clone one-at-a-time. + +#### `giltDir` + +- Type: string +- Default: `~/.gilt/clone` +- Required: no + +Specifies the directory to use for storing cached clones for use by Gilt. The +directory will be created if it does not exist. + +#### `repositories` + +- Type: list +- Default: `[]` +- Required: no + +The list of repositories for Gilt to vendor in. They will be processed in the +order they are defined. + +##### `repositories[].git` + +- Type: string +- Default: None +- Required: yes + +The Git URL of the repository to clone. Any URL format supported by Git may be +used. + +##### `repositories[].version` + +- Type: string +- Default: None +- Required: yes + +The Git commit-ish to use as the source. Any valid branch name, tag name, or +commit hash may be used. + +##### `repositories[].dstDir` + +- Type: string +- Default: None +- Required: no + +The local directory to copy files into. All files in the repository will be +copied. Relative paths will be installed into the directory where `gilt` was +invoked. To copy only a subset of files, use the `repositories.sources` option +instead. + +This option cannot be used with `repositories.sources`. + +##### `repositories[].sources` + +- Type: list +- Default: `[]` +- Required: no + +A list of subtrees and their targets for Gilt to copy. Relative paths will +read/write into the directory where `gilt` was invoked. + +This option cannot be used with `repositories.dstDir`. + +###### `repositories[].sources[].src` + +- Type: string +- Default: None +- Required: yes + +The pathname of the source file/directory to copy. + +###### `repositories[].sources[].dstDir` + +- Type: string +- Default: None +- Required: no + +The pathname of the destination directory. If `src` is a file, it will be placed +inside the named directory. If `src` is a directory, its contents will be copied +into the named directory. All parent directories will be created if they do not +exist. + +This option cannot be used with `repositories[].sources[].dstFile`. + +###### `repositories[].sources[].dstFile` + +- Type: string +- Default: None +- Required: no + +The pathname of the destination file. If `src` is a directory, an error is +thrown. All parent directories will be created if they do not exist, with an +equivalent set of permissions, i.e., a `src` file with mode `0640` will create +all nonexistant intermediate directories with mode `0750`. + +This option cannot be used with `repositories[].sources[].dstDir`. + +##### `repositories[].commands` + +- Type: list +- Default: `[]` +- Required: no + +A list of commands to run after overlaying files. These commands are run in the +same directory used to invoke `gilt`. They will be executed in the order they +are defined, and a non-zero exit status will cause Gilt to abort. + +###### `repositories[].commands[].cmd` + +- Type: string +- Default: None +- Required: yes + +The name of the command to run. The current value of `$PATH` will be used to +find it. This does **NOT** invoke a shell, so variable interpolation, output +redirection, etc., is not supported. + +###### `repositories[].commands[].args` + +- Type: list of strings +- Default: `[]` +- Required: no + +Any and all arguments to the given command. This does **NOT** invoke a shell, so +variable interpolation, output redirection, etc. is not supported. Similarly, +arguments are not split on spaces, so each argument must be a separate list +entry. + +## Env Vars + +The config file can be overriden/defined through env vars. + +```bash +GILT_GILTFILE=Giltfile.yaml \ +GILT_GILTDIR=~/.gilt/clone \ +GILT_DEBUG=false \ +GILT_PARALLEL=false \ +gilt overlay +``` + +### `GILT_DEBUG` + +- Default: `false` + +Enable/disable debug output. + +### `GILT_PARALLEL` + +- Default: `true` + +Enable / disable fetching clones concurrently. The default is to fetch clones in +parallel, with one fetch per CPU, and a maximum of 8 concurrent processes. +Setting `GIT_PARALLEL=false` will cause Gilt to fetch each clone one-at-a-time. + +### `GILT_GILTFILE` + +- Default: `./Giltfile.yaml` + +Configuration file to use. + +### `GILT_GILTDIR` + +- Default: `~/.gilt/clone` + +Specifies the directory to use for storing cached clones for use by Gilt. The +directory will be created if it does not exist. + +### `GILT_SKIPCOMMANDS` + +- Default: `false` + +If set, Gilt will skip running any post-commands when overlaying files. This can +be useful when debugging. + +## Command Flags + +The config file and/or env vars can be overriden/defined through cli flags. + +```bash +gilt \ + --gilt-file=Giltfile.yaml \ + --gilt-dir=~/.gilt/clone \ + --debug \ + --parallel=false \ + overlay +``` + +### `-d`, `--debug` + +Enable debug output. + +### `-c`, `--gilt-dir` + +Path to Gilt's clone dir. (default `~/.gilt/clone`) + +### `-f`, `--gilt-file` + +Path to config file. (default `./Giltfile.yaml`) + +### `--no-commands` + +If set, Gilt will skip running any post-commands when overlaying files. This can +be useful when debugging. + +### `-p`, `--parallel` + +Enable / disable fetching clones concurrently. The default is to fetch clones in +parallel, with one fetch per CPU, and a maximum of 8 concurrent processes. +Setting `--parallel=false` will cause Gilt to fetch each clone one-at-a-time. + + +[Viper]: https://github.com/spf13/viper + diff --git a/docs/versioned_docs/version-2.2.3/contributing.md b/docs/versioned_docs/version-2.2.3/contributing.md new file mode 100644 index 0000000..14e9906 --- /dev/null +++ b/docs/versioned_docs/version-2.2.3/contributing.md @@ -0,0 +1,120 @@ +--- +sidebar_position: 6 +--- + +# Contributing + +Contributions to Gilt are very welcome, but we ask that you read this document +before submitting a PR. + +:::note + +This document applies to the [Gilt][] repository. + +::: + +## Before you start + +- **Check existing work** - Is there an existing PR? Are there issues discussing + the feature/change you want to make? Please make sure you consider/address + these discussions in your work. +- **Backwards compatibility** - Will your change break existing Giltfiles? It is + much more likely that your change will merged if it backwards compatible. Is + there an approach you can take that maintains this compatibility? If not, + consider opening an issue first so that API changes can be discussed before + you invest your time into a PR. + +## 1. Setup + +- **Go** - Gilt is written in [Go][]. We always support the latest two major Go + versions, so make sure your version is recent enough. +- **Node.js** - [Node.js][] is used to host Gilt's documentation server and is + required if you want to run this server locally. + +## 2. Making changes + +- **Code style** - Try to maintain the existing code style where possible. Go + code should be formatted by [`gofumpt`][gofumpt] and linted using + [`golangci-lint`][golangci-lint]. Any Markdown or TypeScript files should be + formatted and linted by [Prettier][]. This style is enforced by our CI to + ensure that we have a consistent style across the project. You can use the + `task fmt:check` command to lint the code locally and the `task fmt` command + to automatically fix any issues that are found. +- **Documentation** - Ensure that you add/update any relevant documentation. See + the [updating documentation](#updating-documentation) section below. +- **Tests** - Ensure that you add/update any relevant tests and that all tests + are passing before submitting the PR. See the [writing tests](#writing-tests) + section below. + +### Running your changes + +To run Gilt with working changes, you can use `go run main.go overlay`. + +### Updating documentation + +Gilt uses [Docusaurus][] to host a documentation server. The code for this is +located in the Gilt repository. This can be setup and run locally by using +`task docs:start` (requires `nodejs` & `yarn`). All content is written in +Markdown and is located in the `docs/docs` directory. All Markdown documents +should have an 80 character line wrap limit (enforced by Prettier). + +### Writing tests + +When making changes, consider whether new tests are required. These tests should +ensure that the functionality you are adding will continue to work in the +future. Existing tests may also need updating if you have changed Gilt's +behavior. + +You may also consider adding unit tests for any new functions you have added. +The unit tests should follow the Go convention of being location in a file named +`*_test.go` in the same package as the code being tested. + +Integration tests are located in the `tests` directory and executed by [Bats][]. + +## 3. Committing your code + +Try to write meaningful commit messages and avoid having too many commits on the +PR. Most PRs should likely have a single commit (although for bigger PRs it may +be reasonable to split it in a few). Git squash and rebase is your friend! + +If you're not sure how to format your commit message, check out [Conventional +Commits][]. This style is enforced, and is a good way to make your commit +messages more readable and consistent. + +## 4. Submitting a PR + +- **Describe your changes** - Ensure that you provide a comprehensive + description of your changes. +- **Issue/PR links** - Link any previous work such as related issues or PRs. + Please describe how your changes differ to/extend this work. +- **Examples** - Add any examples or screenshots that you think are useful to + demonstrate the effect of your changes. +- **Draft PRs** - If your changes are incomplete, but you would like to discuss + them, open the PR as a draft and add a comment to start a discussion. Using + comments rather than the PR description allows the description to be updated + later while preserving any discussions. + +## FAQ + +> I want to contribute, where do I start? + +All kinds of contributions are welcome, whether its a typo fix or a shiny new +feature. You can also contribute by upvoting/commenting on issues or helping to +answer questions. + +> I'm stuck, where can I get help? + +If you have questions, feel free open a [Discussion][] on GitHub. + + +[Gilt]: https://github.com/retr0h/gilt +[Go]: https://go.dev +[Node.js]: https://nodejs.org/en/ +[gofumpt]: https://github.com/mvdan/gofumpt +[golangci-lint]: https://golangci-lint.run +[Prettier]: https://prettier.io/ +[Docusaurus]: https://docusaurus.io +[Discussion]: https://github.com/retr0h/gilt/discussions +[Conventional Commits]: https://www.conventionalcommits.org +[Bats]: https://github.com/bats-core/bats-core + diff --git a/docs/versioned_docs/version-2.2.3/installation.md b/docs/versioned_docs/version-2.2.3/installation.md new file mode 100644 index 0000000..28e67ca --- /dev/null +++ b/docs/versioned_docs/version-2.2.3/installation.md @@ -0,0 +1,23 @@ +--- +sidebar_position: 2 +--- + +# Installation + +## Homebrew Tap + +```bash +brew install retr0h/tap/gilt +``` + +## Go Install + +```bash +go install github.com/retr0h/gilt/v2@latest +``` + +## Python + +```bash +pip3 install python-gilt +``` diff --git a/docs/versioned_docs/version-2.2.3/intro.md b/docs/versioned_docs/version-2.2.3/intro.md new file mode 100644 index 0000000..2110442 --- /dev/null +++ b/docs/versioned_docs/version-2.2.3/intro.md @@ -0,0 +1,42 @@ +--- +slug: / +sidebar_position: 1 +title: Home +--- + +# Gilt + + + +Gilt is a tool which aims to make repo management, manageable. Gilt clones +repositories at a particular version, then overlays the repository to the +provided destination. An alternate approach to "vendoring". + +What makes Gilt interesting, is the ability to overlay particular files and/or +directories from the specified repository to given destinations. Originally, +this was quite helpful for those using Ansible, since libraries, plugins, and +playbooks are often shared, but Ansible's [Galaxy][] has no mechanism to handle +this. Currently, this is proving useful for overlaying [Helm charts][]. + +
+ +## Alternatives + +- [Repo][] +- [Git submodules][] +- [Git subtree][] + +## History + +This project is a golang port of [Gilt][py-gilt], and aims to correct poor +decisions made in the python version, primarially around config syntax, +portability, and reproducibility. + + +[Galaxy]: https://docs.ansible.com/ansible/latest/reference_appendices/galaxy.html +[Helm charts]: https://helm.sh/docs/topics/charts/ +[Repo]: https://gerrit.googlesource.com/git-repo/+/refs/heads/master/README.md +[Git submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules +[Git subtree]: https://github.com/git/git/blob/master/contrib/subtree/git-subtree.txt +[py-gilt]: http://gilt.readthedocs.io/en/latest/ + diff --git a/docs/versioned_docs/version-2.2.3/testing.md b/docs/versioned_docs/version-2.2.3/testing.md new file mode 100644 index 0000000..2fac839 --- /dev/null +++ b/docs/versioned_docs/version-2.2.3/testing.md @@ -0,0 +1,29 @@ +--- +sidebar_position: 5 +--- + +# Testing + +Check installed dependencies: + +```bash +task deps:check +``` + +To execute tests: + +```bash +task test +``` + +Auto format code: + +```bash +task fmt +``` + +List helpful targets: + +```bash +task +``` diff --git a/docs/versioned_docs/version-2.2.3/usage.md b/docs/versioned_docs/version-2.2.3/usage.md new file mode 100644 index 0000000..4f9468c --- /dev/null +++ b/docs/versioned_docs/version-2.2.3/usage.md @@ -0,0 +1,67 @@ +--- +sidebar_position: 4 +--- + +# Usage + +## CLI + +### Init Configuration + +Initializes config file in the shell's current working directory: + +```bash +gilt init +``` + +### Overlay Repository + +Overlay a remote repository into the destination provided. + +```bash +gilt overlay +``` + +### Debug + +Display the git commands being executed. + +```bash +gilt --debug overlay +``` + +### Skipping post-commands + +Overlay files only, but run no other commands. + +```bash +gilt overlay --no-commands +``` + +## Package + +### Overlay Repository + +See example client in `examples/go-client/`. + +```go +func main() { + debug := true + logger := getLogger(debug) + + c := config.Repositories{ + Debug: debug, + GiltDir: "~/.gilt", + Repositories: []config.Repository{ + { + Git: "https://github.com/retr0h/ansible-etcd.git", + Version: "77a95b7", + DstDir: "../tmp/retr0h.ansible-etcd", + }, + }, + } + + var r repositoriesManager = repositories.New(c, logger) + r.Overlay() +} +``` diff --git a/docs/versioned_sidebars/version-2.2.3-sidebars.json b/docs/versioned_sidebars/version-2.2.3-sidebars.json new file mode 100644 index 0000000..39332bf --- /dev/null +++ b/docs/versioned_sidebars/version-2.2.3-sidebars.json @@ -0,0 +1,8 @@ +{ + "docsSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/docs/versions.json b/docs/versions.json index c22e943..612d68f 100644 --- a/docs/versions.json +++ b/docs/versions.json @@ -1,4 +1,5 @@ [ + "2.2.3", "2.2.2", "2.2.1", "2.2",