Merge pull request #1906 from rsteube/more-changelog

doc: migrated more changelogs
carapace-sh · Oct 13, 2023 · a18b534 · a18b534
2 parents ee25832 + 02f738c
commit a18b534
Show file tree

Hide file tree

Showing 33 changed files with 231 additions and 723 deletions.
diff --git a/docs/book.toml b/docs/book.toml
@@ -7,7 +7,7 @@ title = "carapace-bin"
 
 [output.html]
 default-theme = "Mocha"
-additional-css = ["asciinema/asciinema-player.css", "./theme/catppuccin.css", "./theme/catppuccin-highlight.css"]
+additional-css = ["asciinema/asciinema-player.css", "./theme/catppuccin.css"]
 additional-js = ["asciinema/asciinema-player.min.js", "asciinema/load.js"]
 git-repository-url = "https://github.com/rsteube/carapace-bin"
 edit-url-template = "https://github.com/rsteube/carapace-bin/edit/master/docs/{path}"

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -31,3 +31,18 @@
     - [v0.28](./changelog/v0.28.md)
     - [v0.27](./changelog/v0.27.md)
     - [v0.26](./changelog/v0.26.md)
+    - [v0.25](./changelog/v0.25.md)
+    - [v0.24](./changelog/v0.24.md)
+    - [v0.23](./changelog/v0.23.md)
+    - [v0.22](./changelog/v0.22.md)
+    - [v0.21](./changelog/v0.21.md)
+    - [v0.20](./changelog/v0.20.md)
+    - [v0.19](./changelog/v0.19.md)
+    - [v0.18](./changelog/v0.18.md)
+    - [v0.17](./changelog/v0.17.md)
+    - [v0.16](./changelog/v0.16.md)
+    - [v0.15](./changelog/v0.15.md)
+    - [v0.14](./changelog/v0.14.md)
+    - [v0.13](./changelog/v0.13.md)
+    - [v0.12](./changelog/v0.12.md)
+    - [v0.11](./changelog/v0.11.md)
diff --git a/...log/in_the_style_of_gravityfalls__espresso_machine_S1601100496_St50_G7.5(1).png b/...log/in_the_style_of_gravityfalls__espresso_machine_S1601100496_St50_G7.5(1).png
diff --git a/docs/src/changelog/v0.11.md b/docs/src/changelog/v0.11.md
@@ -0,0 +1,29 @@
+# v0.11 - Puking Rainbows
+
+![](./v0.11/banner.png)
+
+This release adds color support for `zsh` and `elvish` and thus raises `elvish` minimum version to `v0.18.0`.
+
+![](./v0.11/rainbow.png)
+
+## LS_COLORS
+`LS_COLORS` should now be working correctly - e.g with [vivid](https://github.com/sharkdp/vivid) in `elvish`:
+```sh
+set E:LS_COLORS = (vivid generate dracula)
+```
+
+![](./v0.11/lscolors1.png)
+
+![](./v0.11/lscolors2.png)
+
+## Style Config
+
+Styles can now be configured with `carapace --style key=value` (an empty value restores the default).
+
+![](./v0.11/style-config.png)
+
+## Powershell Style
+
+Added color support for powershell.
+
+![](./v0.11/powershell.png)
diff --git a/docs/src/changelog/v0.11/162618295-b947f846-32fb-4b2b-b371-aef75636cd83.png b/docs/src/changelog/v0.11/162618295-b947f846-32fb-4b2b-b371-aef75636cd83.png
diff --git a/docs/src/changelog/v0.11/banner.png b/docs/src/changelog/v0.11/banner.png
diff --git a/docs/src/changelog/v0.11/lscolors1.png b/docs/src/changelog/v0.11/lscolors1.png
diff --git a/docs/src/changelog/v0.11/lscolors2.png b/docs/src/changelog/v0.11/lscolors2.png
diff --git a/docs/src/changelog/v0.11/powershell.png b/docs/src/changelog/v0.11/powershell.png
diff --git a/docs/src/changelog/v0.11/rainbow.png b/docs/src/changelog/v0.11/rainbow.png
diff --git a/docs/src/changelog/v0.11/style-config.png b/docs/src/changelog/v0.11/style-config.png
diff --git a/docs/src/changelog/v0.12.md b/docs/src/changelog/v0.12.md
@@ -0,0 +1,73 @@
+# v0.12 - Preinfusion
+
+![](./v0.12/banner.png)
+
+## Preinvoke
+
+Generic alteration of completion before execution which enables features like directory change in `git -C <DIR>`:
+
+![](./v0.12/preinvoke.png)
+
+## Spec
+
+Experimental support for simple completions using `yaml` [spec files](https://github.com/rsteube/carapace-spec/tree/master/example):
+
+```yaml
+name: example
+description:
+flags:
+  --dynamic=: dynamic value
+  -o, --optarg?: optarg flag
+  -s, --styled=: styled values
+completion:
+  flag:
+    dynamic: ["$(git branch --all | cut -c 3- | sed 's/$/\t\tblue/')", "static value"]
+    optarg: ["first", "second", "third"]
+    styled:
+    - "blue\tblue\tblue"
+    - "cyan\tcyan\tcyan"
+  positional:
+  -  ["pos1-a", "pos1-b", "pos1-c"]
+  -  ["$_files"]
+```
+
+## Spec Autoloading
+
+Specs placed in `${UserConfigDir}/carapace/specs/` ([UserConfigDir](https://pkg.go.dev/[email protected]#UserConfigDir)) are now registered with `carapace _carapace`.
+File name must be the command to be completed and match `^[0-9a-zA-Z_\-.]+\.yaml$` (sanity check to avoid breakage in scripts).
+
+## Custom Macros
+
+Exposed [actions](https://pkg.go.dev/github.com/rsteube/carapace-bin/pkg/actions) as custom macros (list with `carapace --macros`).
+Removed the `_` prefix from core macros to avoid clashes (e.g. `$files`, `$directories`).
+
+## Macro Arguments
+Arguments are parsed as `yaml` (`$macro(yaml)` - e.g.: `$_tools.gh.Users({users: true})`).
+Brackets are optional when no argument is passed (`$files` instead of `$files()`).
+
+## Variable Substitution
+
+Variables are replaced using [drone/envsubst](https://github.com/drone/envsubst) for contextual completion:
+
+```yaml
+name: myzip
+completion:
+  positional:
+    - ["$files([.zip])"] # ${C_ARG0}
+  positionalany: ["$_fs.ZipFileContents(${C_ARG0})"] # ${C_ARG1},${C_ARG2},...
+```
+
+Flags are only added to env when their value changed (thus: `${C_FLAG_FLAGNAME:-default}`):
+
+```yaml
+name: myrefs
+flags:
+  --tags: list tags # ${C_FLAG_TAGS}
+  --localbranches: list local branches # ${C_FLAG_LOCALBRANCHES}
+  --commits=: amount of commits # ${C_FLAG_COMMITS}
+completion:
+  positional:
+    - ["$_tools.git.Refs({tags: ${C_FLAG_TAGS:-false}, localbranches: ${C_FLAG_LOCALBRANCHES:-false}, commits: ${C_FLAG_COMMITS:-0}})"] # refs based on flag values with defaults
+    - ["$_tools.git.Refs"] # default refs
+    - ["$(env)"] # env
+```
diff --git a/docs/src/changelog/v0.12/banner.png b/docs/src/changelog/v0.12/banner.png
diff --git a/docs/src/changelog/v0.12/preinvoke.png b/docs/src/changelog/v0.12/preinvoke.png
diff --git a/docs/src/changelog/v0.13.md b/docs/src/changelog/v0.13.md
@@ -0,0 +1 @@
+# v0.13
diff --git a/docs/src/changelog/v0.14.md b/docs/src/changelog/v0.14.md
@@ -0,0 +1 @@
+# v0.14
diff --git a/docs/src/changelog/v0.15.md b/docs/src/changelog/v0.15.md
@@ -0,0 +1 @@
+# v0.15
diff --git a/docs/src/changelog/v0.16.md b/docs/src/changelog/v0.16.md
@@ -0,0 +1 @@
+# v0.16
diff --git a/docs/src/changelog/v0.17.md b/docs/src/changelog/v0.17.md
@@ -0,0 +1,85 @@
+# v0.17 - Spec-tacular Citizen
+
+![](./v0.17/banner.png)
+
+[Specs] are now first-class citizens in carapace. They are integrated on root level and should behave similar to the existing completers (`carapace [spec.name] <TAB>`).
+
+## List
+
+Completers based on [Specs] are highlighted in shells that support colors (details: `carapace --list=json`):
+
+![](./v0.17/list.png)
+
+## Bridge
+
+Using [Specs] for [bridging](../spec/bridge.html) is from now on the recommended approach.
+As these are auto-loaded with `carapace _carapace` and provide support for embedded completion like `sudo [spec.name] <TAB>`.
+
+Existing completers with the same name will also be overridden.
+E.g. `kubectl` (which is currently a bit outdated) can be configured to use the official completer:
+
+```yaml
+# ${UserConfigDir}/carapace/specs/kubectl.yaml
+name: kubectl
+description: kubectl controls the Kubernetes cluster manager
+completion:
+  positionalany: ["$_bridge.Cobra(kubectl)"]
+```
+
+> Note that bridging adds a slight overhead (~7-9ms?) for each invocation and is limited to supported frameworks / commands.
+
+
+## Plugin
+
+Taking this one step further plugin completion like `cargo-[plugin]`, `gh-[plugin]`, `git-[plugin]` can now also be defined by [Specs].
+
+E.g. the [gh-repo-collab](https://github.com/mislav/gh-repo-collab) extension for [github-cli](https://cli.github.com/):
+```yaml
+# ${UserConfigDir}/carapace/specs/gh-repo-collab.yaml
+name: gh-repo-collab
+description: manage repository collaborators
+commands:
+  -
+    name: list
+    completion:
+      positional:
+        - ["$_tools.gh.OwnerRepositories"]
+  -
+    name: add
+    flags:
+      --permission=: set permission
+    completion:
+      flag:
+        permission: ["pull", "triage", "push", "maintain", "admin\t\tred"]
+      positional:
+        - ["$_tools.gh.OwnerRepositories"]
+        - ["$_tools.gh.Users"]
+  -
+    name: remove
+    completion:
+      positional:
+        - ["$_tools.gh.OwnerRepositories"]
+        - ["$_tools.gh.Users"]
+```
+
+![](./v0.17/plugin.png)
+
+## Nushell
+
+With https://github.com/nushell/nushell/pull/6652 (upcoming [v0.70.0](https://github.com/nushell/nushell/milestone/11?closed=1)) the [nushell] integration is now working on positional arguments.
+The recommended configuration is equivalent to the example configuration in `config.nu`:
+
+```nu
+let carapace_completer = {|spans| 
+  carapace $spans.0 nushell $spans | from json
+}
+
+let-env config = {
+  external_completer: $carapace_completer
+}
+```
+
+> Be sure to remove the `module completions` example so that it won't override the carapace completion
+
+[nushell]:https://www.nushell.sh/
+[Specs]:https://github.com/rsteube/carapace-spec
diff --git a/docs/src/changelog/v0.17/banner.png b/docs/src/changelog/v0.17/banner.png
diff --git a/docs/src/changelog/v0.17/list.png b/docs/src/changelog/v0.17/list.png
diff --git a/docs/src/changelog/v0.17/plugin.png b/docs/src/changelog/v0.17/plugin.png
diff --git a/docs/src/changelog/v0.18.md b/docs/src/changelog/v0.18.md
@@ -0,0 +1 @@
+# v0.18
diff --git a/docs/src/changelog/v0.19.md b/docs/src/changelog/v0.19.md
@@ -0,0 +1 @@
+# v0.19
diff --git a/docs/src/changelog/v0.20.md b/docs/src/changelog/v0.20.md
@@ -0,0 +1 @@
+# v0.20
diff --git a/docs/src/changelog/v0.21.md b/docs/src/changelog/v0.21.md
@@ -0,0 +1 @@
+# v0.21
diff --git a/docs/src/changelog/v0.22.md b/docs/src/changelog/v0.22.md
@@ -0,0 +1 @@
+# v0.22
diff --git a/docs/src/changelog/v0.23.md b/docs/src/changelog/v0.23.md
@@ -0,0 +1 @@
+# v0.23
diff --git a/docs/src/changelog/v0.24.md b/docs/src/changelog/v0.24.md
@@ -0,0 +1,17 @@
+# v0.24 - Spring Cleaning
+
+![](./v0.24/banner.png)
+
+## carapace-bridge
+
+Moved bridge actions to [carapace-bridge].
+The shell bridges now use custom configs at  [`${UserConfigDir}/carapace/bridge`]
+(e.g. `~/.config/carapace/bridge/fish/config.fish` instead of `~/.config/fish/config.fish`).
+
+## removed flags
+
+Removed `--bridge` and `--spec` flags as user specs are preferred and there are [carapace-bridge] and [carapace-spec] as well.
+
+[`${UserConfigDir}/carapace/bridge`]:https://pkg.go.dev/os#UserConfigDir
+[carapace-bridge]:https://github.com/rsteube/carapace-bridge
+[carapace-spec]:https://github.com/rsteube/carapace-spec
diff --git a/docs/src/changelog/v0.24/banner.png b/docs/src/changelog/v0.24/banner.png
diff --git a/docs/src/changelog/v0.25.md b/docs/src/changelog/v0.25.md
@@ -0,0 +1 @@
+# v0.25