From 66d56e794c8edf2e0a446c965bfad278f9c50ace Mon Sep 17 00:00:00 2001 From: David Aguilar Date: Thu, 14 Dec 2023 23:05:36 -0800 Subject: [PATCH] doc: spelling fixes and minor tweaks --- doc/src/README.md | 6 +++--- doc/src/changelog.md | 8 ++++---- doc/src/commands.md | 26 +++++++++++++------------- doc/src/configuration.md | 33 +++++++++++++++------------------ doc/src/glossary.md | 8 ++++---- doc/src/installation.md | 8 ++++---- doc/src/tree-queries.md | 6 +++--- 7 files changed, 46 insertions(+), 49 deletions(-) diff --git a/doc/src/README.md b/doc/src/README.md index aab1442..25ab402 100644 --- a/doc/src/README.md +++ b/doc/src/README.md @@ -6,13 +6,13 @@ Garden streamlines development workflows that involve a loosely-coupled set of multiple, independent Git trees. Garden allows you to define dynamic relationships and workflows between these -repositories using a declarative YAML config file that can be shared and used as -a bootstrapping mechanism for getting a auditable, from-source project cloned, +repositories using a YAML configuration file that can be shared and used as +a bootstrapping mechanism for getting an audit-able, from-source project cloned, built, installed and running with minimal effort for consumers of a Garden file. Garden sits above any individual project's build scripts and conventions. Garden is all about making it easy to remix and reuse libraries maintained -in seperate Git repositories. +in separate Git repositories. ### Project Links diff --git a/doc/src/changelog.md b/doc/src/changelog.md index 20a5687..cc42fe0 100644 --- a/doc/src/changelog.md +++ b/doc/src/changelog.md @@ -72,7 +72,7 @@ referenced using `graft::` namespace qualifiers. This behavior allows a tree definition to replace just the `url` field, or to replace individual tree commands while retaining the rest. Use `replace: true` in a Tree definition in order to completely replace the existing entry instead of sparsely - overridding it. + overriding it. - Improved shell completions for `garden`, `garden init` and `garden plant`. @@ -89,7 +89,7 @@ referenced using `graft::` namespace qualifiers. **Features**: - Both names and values in `gitconfig` can now use `${var}` expressions. - Previously only values were evaluated. Config names are evaluated now as well. + Previously only values were evaluated. Names are evaluated now as well. **Fixes**: @@ -105,7 +105,7 @@ referenced using `graft::` namespace qualifiers. **Fixes** - Exec expressions were previously run with the current directory set to the - directory from which garden was run. Exec expresssions are now run in the + directory from which garden was run. Exec expressions are now run in the tree's current directory. ## v0.5.0 @@ -222,7 +222,7 @@ referenced using `graft::` namespace qualifiers. This is the initial garden release. - `garden grow` grows worktrees. -- `garden init` intitializes configuration. +- `garden init` initializes configuration. - `garden plant` (formerly `garden add`) adds existing trees. - `garden cmd` and `garden ` can run custom commands. - Templates, variables, and environment variables are all supported. diff --git a/doc/src/commands.md b/doc/src/commands.md index 25f21d2..626d807 100644 --- a/doc/src/commands.md +++ b/doc/src/commands.md @@ -24,14 +24,14 @@ The following options come before `` and are common to all commands. -C | --chdir -chdir to the specified directory before searching for configuration. +Navigate to the specified directory before searching for configuration. This is modeled after `make -C ...` or `git -C ...`. -c | --config -Specify a garden config file to use instead of searching for `garden.yaml`. -The path can either be the path to an actual config file, or it can be -the basename of a file in the configuration search path. +Specify a garden file to use instead of searching for `garden.yaml`. +The filename can be either the path to a file or the basename of a file in the +configuration search path. -v | --verbose @@ -119,7 +119,7 @@ and places them into the paths defined by the garden file. It is safe to re-run the `grow` command and re-grow a tree. Existing trees will have their git configuration updated to match the configured remotes. Missing -repositories are created by cloning the configured tree url. +repositories are created by cloning the configured tree URL. ### Branches @@ -155,14 +155,14 @@ git clone --depth=42 --no-single-branch ``` Even though a shallow clone is created, all of the remote tracking branches -(eg. `origin/*`) are available because we clone the repository using +(e.g. `origin/*`) are available because we clone the repository using the `--no-single-branch` option. The `single-branch: true` tree parameter is used to create clones that contain a single branch only. This is useful if you want to limit the on-disk footprint of repositories by only having a single branch available. -This paramter is typically used in conjunction with `branch: ` and +This par mater is typically used in conjunction with `branch: ` and `depth: 1` to create a 1-commit shallow clone with a single branch. ```yaml @@ -342,7 +342,7 @@ environment from the corresponding garden, group, or tree. Multi-line and multi-statement command strings will stop executing as soon as the first non-zero exit code is encountered due to the use of the `-e` shell option. -Use the `-n | --no-errexit` option to inhibit the use of the `-e` errexit option. +Use the `-n | --no-errexit` option to inhibit the use of the `-e` "errexit" option. The `--no-errexit` option causes commands with multiple statements to run to completion even when a non-zero exit code is encountered. This is akin to a regular shell script. @@ -363,7 +363,7 @@ subsequent variables will be set according to each argument. ```yaml # Commands can be defined in multiple ways. # Strings and lists of strings are both supported via "String to List Promotion". -# The YAML reader accepts multi-line strings using the the "|" pipe syntax. +# The YAML reader accepts multi-line strings using the "|" pipe syntax. commands: one-liner: echo hello "$@" @@ -422,8 +422,8 @@ The plain `$variable` syntax is reserved for use by the shell commands used in user-defined Commands and Exec Expressions. Environment Variables can be used in shell scriptlets through both the `$ENV` and -`${ENV}` braced variable syntax. Garden makes `${PATH}` and all other environment -variables available during variable expansion. +`${ENV}` braced variable syntax. Garden makes all environment variables available during +variable expansion. The distinction between the `${garden}` and `$shell` syntax is only relevant when using variables defined within shell command, such as `$shell_variable` above. @@ -433,7 +433,7 @@ empty value would have been used instead of the output of `date +%s`. Sometimes it is necessary to actually use the `${...}` braced literal syntax in shell commands. The `$${...}` braced double-dollar syntax can be used to -escape a braced value and disable evalution by `garden`. +escape a braced value and disable evaluation by `garden`. Double-`$` can generally be used to escape literal `$` values in commands, but escaping is handled automatically for regular `$shell` variables. @@ -555,7 +555,7 @@ Traverse the filesystem and interactively delete any repositories that are not referenced by the garden file. This command is intended to cleanup a garden-managed directory. Its intended -usage is to delete repositories that were created (eg. via `garden grow`) and +usage is to delete repositories that were created (e.g. via `garden grow`) and have since been removed from your version-controlled garden configuration. **Warning**: `garden prune` is a dangerous command and must be run with care. diff --git a/doc/src/configuration.md b/doc/src/configuration.md index dfb495a..5c7c145 100644 --- a/doc/src/configuration.md +++ b/doc/src/configuration.md @@ -123,7 +123,7 @@ If an include file is not found relative to the current garden file then a path to the root configuration directory will be checked for the existence of the file. Includes files are treated like "optional" includes -- include files that cannot be -found are silenty ignored. +found are silently ignored. Enable the `garden -d config ...` debug flag to display warnings about missing include files. @@ -137,7 +137,7 @@ Entities in garden files such as `trees`, `gardens`, `groups`, `commands` and When the same entry is found in multiple included files then the only last definition will be used. This is referred to as the "Last One Wins" rule. -Entities defined in the the root `garden.yaml` have the highest precedence and override +Entities defined in the root `garden.yaml` have the highest precedence and override entries provided via `garden.includes`. `variables`, `commands`, `groups` and `gardens` are completely replaced when multiple @@ -219,7 +219,7 @@ override/replace variables defined in a tree scope. Garden automatically defines some built-in variables that can be useful when constructing values for variables, commands, and paths. -* **GARDEN_CONFIG_DIR** -- Directory containing the `garden.yaml` config file. +* **GARDEN_CONFIG_DIR** -- Directory containing the `garden.yaml` file. * **GARDEN_ROOT** -- Root directory for trees. * **TREE_NAME** -- Current tree name. * **TREE_PATH** -- Current tree path. @@ -228,18 +228,13 @@ when constructing values for variables, commands, and paths. The "environment" block defines variables that are stored in the environment. -Environment variables are resolved in the same order as the garden variables: +Environment variables are resolved in the same order as garden variables: global scope, tree scope, and garden scope. This allows gardens to prepend/append variables after a tree, thus allowing for customization of behavior from the garden scope. -Environment variables are resolved after garden variables. This allows -the use of garden variables when defining environment variable values. - -Environment variable names can use garden `${variable}` syntax when defining -both their name and values. - -Values in environment blocks prepend to the named environment variable. +Values in environment blocks prepend to the environment variable by default. +The `:` UNIX path separator is used when prepending and appending values. ```yaml trees: @@ -248,7 +243,7 @@ trees: PATH: ${TREE_PATH}/bin ``` -The example above prepends the `foo/bin` directory to the colon (`:`)-delimeted `PATH` +The example above prepends the `foo/bin` directory to the colon (`:`)-delimited `PATH` environment variable. Names with an equals sign (`=`) suffix are treated as "store" operations and are @@ -261,8 +256,10 @@ trees: ${TREE_NAME}_LOCATION=: ${TREE_PATH} ``` -The example above exports a variable called `foo_LOCATION` with the location of the tree. -If `foo_LOCATION` is already defined then its value is replaced. +Environment variable entries can use garden `${variable}` syntax when defining +both their name and values. The example above exports a variable called `foo_LOCATION` +with the location of the tree. If `foo_LOCATION` is already defined then its value is +replaced. A plus sign (`+`) suffix in the name append to a variable instead of prepending. @@ -422,7 +419,7 @@ trees: message: The time is now: $(date) ``` -When a tree specifies multiple templates then all of the tempaltes are merged into +When a tree specifies multiple templates then all of the templates are merged into the tree's definitions. If variables are multiply-defined across multiple templates then the variable's value from the last specified template will be used. @@ -471,7 +468,7 @@ wildcard patterns. The "annex" group definition is: `annex/*`. This matches all trees that start with "annex/". The "git-all" group has two entries -- `git*` and -`cola`. the first matches all trees that start with "git", and the second one +`cola`. The first matches all trees that start with "git", and the second one matches "cola" only. @@ -497,7 +494,7 @@ A more advanced modularity feature allow you to stitch additional `garden.yaml` files underneath a custom "graft namespace". The example below demonstrates how to define trees and variables in separate -"graft" files and refer to them using a `graft::` namespace qualfier. +"graft" files and refer to them using a `graft::` namespace qualifier. ```yaml # Top-level garden.yaml @@ -544,7 +541,7 @@ variables: Running `garden eval '${graft::value}'` will output `grafted value`. -Running `garden eval '${value}'` wil output `global grafted value`, as it evaluates at +Running `garden eval '${value}'` will output `global grafted value`, as it evaluates at global scope. Running `garden eval '${value}' local-tree` will output `local grafted value`, as it diff --git a/doc/src/glossary.md b/doc/src/glossary.md index edf97d2..de02afd 100644 --- a/doc/src/glossary.md +++ b/doc/src/glossary.md @@ -57,9 +57,9 @@ matching set of trees. If searching for gardens finds matches then groups and trees are not searched. If searching for groups finds matches then trees are not searched. Prefix the tree query pattern with a percent-sign (`%`), - eg. `%group*`, to only query for groups matching the pattern. - Prefix the pattern with an at-sign (`@`), eg. `@tree`, to only query for trees. - Prefix the pattern with colon (`:`), eg. `:garden`, to only query for gardens. + e.g. `%group*`, to only query for groups matching the pattern. + Prefix the pattern with an at-sign (`@`), e.g. `@tree`, to only query for trees. + Prefix the pattern with colon (`:`), e.g. `:garden`, to only query for gardens. The `:garden` syntax is not typically used because gardens are already searched first. `%group` and `@tree` can be used to disambiguate queries for groups and trees that share the same name as a garden. @@ -68,7 +68,7 @@ String values can use shell `${variables}` expressions to interpolate and expand values in the string. `~` is expanded to `$HOME`. These expressions can be used in most fields where strings are accepted, - eg. when definiting variables, commands and environment variables. + e.g. when defining variables, commands and environment variables. * **exec expressions** When a *string expression* starts with `$ ` (dollar-sign then space) then the diff --git a/doc/src/installation.md b/doc/src/installation.md index 10da9fc..da4aea4 100644 --- a/doc/src/installation.md +++ b/doc/src/installation.md @@ -16,7 +16,7 @@ and prefer to install `garden` using `pkgin` or the pkgsrc/NetBSD sources. If you already have `cargo` installed then you can skip this section. You may be able to install `cargo` on macOS and Linux using standard package -managers, eg. `brew install rust` or `apt install rust-all`. +managers, e.g. `brew install rust` or `apt install rust-all`. Other platforms and older distributions can get a Rust development toolchain by going to [rustup.rs and following the installation instructions](https://rustup.rs). @@ -131,10 +131,10 @@ cargo install --path . Running `cargo install` with no arguments installs to `~/.cargo/bin/garden` by default. Once you have `garden` installed then you can use Garden's `garden.yaml` to run -Garden's custom worfkflow commands. +Garden's custom workflow commands. * `garden test` runs the test suite using `cargo test`. -* `garden check` runs checks and linters. +* `garden check` runs checks and lints. * `garden doc` builds the documentation. * `garden fmt` formats the source code. * `garden install-doc` installs the documentation. @@ -148,7 +148,7 @@ Garden is developed on Linux and supported on macOS and BSDs where Rust is avail Garden is not supported on Windows. -Garden "should" work fine on Windows if you install a shell (eg. `bash.exe` or +Garden "should" work fine on Windows if you install a shell (e.g. `bash.exe` or `zsh.exe`) in `$PATH` and patch a few details to deal with Windows-isms, but Garden is untested and not supported by the core team on Windows or WSL. diff --git a/doc/src/tree-queries.md b/doc/src/tree-queries.md index 1b25d58..05494ce 100644 --- a/doc/src/tree-queries.md +++ b/doc/src/tree-queries.md @@ -49,14 +49,14 @@ garden cmd cola status build ## Paths Paths can be specified as well, but the filesystem has the lowest priority -relative to gardens, groups, and trees. When specifyiing paths they must -resolve to a configured tree. For example, +relative to gardens, groups, and trees. When specifying paths they must +resolve to a configured tree. For example: ```bash garden build . -- --verbose ``` -runs the `build` command on the tree in the current directory and passes the +This runs the `build` command on the tree in the current directory and passes the `--verbose` flag to the configured `build` command.