doc: added spec run

completers/git_completer/cmd/lsRemote.go

@@ -28,6 +28,8 @@ func init() {
 	lsRemoteCmd.Flags().String("upload-pack", "", "path of git-upload-pack on the remote host")
 	rootCmd.AddCommand(lsRemoteCmd)
 
+	lsRemoteCmd.Flag("sort").NoOptDefVal = " "
+
 	carapace.Gen(lsRemoteCmd).FlagCompletion(carapace.ActionMap{
 		"sort": git.ActionFieldNames(),
 	})

docs/src/SUMMARY.md

@@ -10,6 +10,8 @@
     - [User](./spec/user.md)
     - [Bridge](./spec/bride.md)
     - [Embed](./spec/embed.md)
+    - [Run](./spec/run.md)
+    - [Shim](./spec/shim.md)
     - [Generate](./spec/generate.md)
     - [Scrape](./spec/scrape.md)
     - [Examples](./spec/examples.md)

docs/src/spec/bride.md

@@ -35,7 +35,7 @@ completion:
 [Completers](../completers.md) and [Specs](../spec.md) registered in [rsteube/carapace-bin] can be bridged with the [`bridge.CarapaceBin`] macro:
 
 ```yaml
-name: gh
+name: github-cli
 description: Work seamlessly with GitHub from the command line
 completion:
   positionalany: ["$_bridge.CarapaceBin(gh)"]

docs/src/spec/examples.md

@@ -39,3 +39,64 @@ completion:
 ```
 
 ![](./examples-refs.cast)
+
+
+## g.yaml
+
+```yaml
+name: g
+commands:
+  - name: checkout
+    description: Switch branches or restore working tree files
+    group: git
+    run: "[git, checkout]"
+
+  - name: commit
+    description: Record changes to the repository
+    group: git
+    run: "[git, commit]"
+
+  - name: diff
+    description: Show changes between commits
+    group: git
+    run: "[git, diff]"
+
+  - name: log
+    description: Show commit logs
+    group: git
+    run: "[git, log]"
+
+  - name: push
+    description: Update remote refs along with associated objects
+    group: git
+    run: "[git, push]"
+
+  - name: switch
+    description: Switch branches
+    group: git
+    run: "[git, checkout]"
+
+  - name: issue
+    description: Manage issues
+    group: gh
+    run: "[gh, issue]"
+    commands:
+      - name: bugs
+        description: List bugs
+        run: "[gh, issue, list, --label, bug]"
+
+  - name: pr
+    description: Manage pull requests
+    group: gh
+    run: "[gh, pr]"
+
+  - name: edit
+    description: Edit changed files
+    run: "$(hx $@)"
+    flags:
+      -s, --staged: include staged files
+    completion:
+      positionalany: ["$_tools.git.Changes({staged: ${C_FLAG_STAGED:-false}, unstaged: true})"]
+```
+
+![](./examples-g.cast)

docs/src/spec/run.md

@@ -0,0 +1,34 @@
+# Run
+
+Specs containing a `run` field can be executed using [Shims](shim.md).
+
+## Alias
+
+Alias bridges a command while retaining the argument completion.
+
+```yaml
+name: log-by-author
+run: "[git, log, --author]"
+```
+
+![](./run-alias.cast)
+
+## Script
+
+Script macro is executed with `sh` on unix systems and `pwsh` on windows.
+Flags are used for [environment substitution](https://github.com/drone/envsubst) and positional arguments are passed to the script.
+
+```yaml
+name: ls-remote
+run: "$(git ls-remote --sort='${C_FLAG_SORT:-HEAD}' $@)"
+flags:
+  --sort=: field name to sort on
+completion:
+  flag:
+    sort: [version:refname, authordate]
+  positional:
+    - ["$_tools.git.RepositorySearch"]
+  positionalany: ["$_tools.git.LsRemoteRefs({url: '${C_ARG0}', branches: true, tags: true})"]
+```
+
+![](./run-script.cast)

docs/src/spec/shim.md

@@ -0,0 +1,15 @@
+# Shim
+
+Whe `carapace _carapace` is invoked it  creates [shims] in [`${UserConfigDir}/carapace/bin`] for [runnable specs].
+
+For unix systems this is a simple shell script, but for windows an [embedded binary] is used.
+
+```sh
+#!/bin/sh
+carapace --run "/home/rsteube/.config/carapace/specs/runnable.yaml" "$@"
+```
+
+[`${UserConfigDir}/carapace/bin`]:https://pkg.go.dev/os#UserConfigDir
+[embedded binary]:https://github.com/rsteube/carapace-bin/blob/master/cmd/shim/main.go
+[runnable specs]:run.md
+[shims]:https://en.wikipedia.org/wiki/Shim_(computing)