doc: updated git

Author: rsteube

docs/src/freckles.md

@@ -8,7 +8,7 @@
 
 [Freckles] is based on [Carapace] and serves as an example application.
 
-The following documentation thus covers implementation details and highlights how [Carapace] provides completion.
+The following documentation thus covers implementation details and highlights how completions are provided.
 
 [Carapace]:https://carapace.sh
 [dotfile]:https://dotfiles.github.io/

docs/src/freckles/cmd/edit.md

@@ -40,7 +40,7 @@ Completion is provided with a [custom action].
 >
 > ---
 >
-> The [Walk] function returns dotfiles with their full path within the repository: `path/to/freckle`.
+> The [Walk] function returns dotfiles with their full path within the repository: `path/to/file`.
 > By modifying the [Action] with [MultiParts] the segments get completed separately.
 >
 > ---

docs/src/freckles/cmd/git.md

@@ -18,6 +18,29 @@ Completion is provided with [`ActionCarapaceBin`].
 
 ![](./git/git.cast)
 
+> Without arguments [`ActionCarapaceBin`] completes all registered commands.
+>
+> Here, we limit it to `git`.
+> But it could be even more specific by passing subcommands, flags and arguments.
+>
+> ---
+>
+> Just as above we change the directory with [Chdir] to the repository.
+>
+> Note that [Carapace] also supports generic modifications like `-C <dir>` with [PreInvoke].
+>
+> ---
+>
+> When fully embedding a command `DisableFlagParsing: true` is the right aproach.
+>
+> But for [sudo]-like behaviour where the local command has flags as well there is [SetInterspersed].
+> Disabling it stops flag parsing after the first positional argument.
+
 [`ActionCarapaceBin`]:https://pkg.go.dev/github.com/carapace-sh/carapace-bridge/pkg/actions/bridge#ActionCarapaceBin
+[Carapace]:https://carapace.sh
+[Chdir]:https://carapace-sh.github.io/carapace/carapace/action/chdir.html
 [Freckles]:https://github.com/carapace-sh/freckles
 [Git]:https://git-scm.com/
+[sudo]:https://github.com/carapace-sh/carapace-bin/blob/master/completers/sudo_completer/cmd/root.go
+[PreInvoke]:https://carapace-sh.github.io/carapace/carapace/gen/preInvoke.html
+[SetInterspersed]:https://pkg.go.dev/github.com/spf13/pflag#SetInterspersed

docs/src/freckles/cmd/init.md

@@ -12,7 +12,7 @@ Creates a new [Git] repository at `~/.local/share/freckles`.
 
 Alternatively an existing remote repository can be cloned with the `--clone` flag.
 
-Completion is provided by [ActionRepositorySearch].
+Completion is provided with [ActionRepositorySearch].
 
 ```go
 {{#include ../../../../cmd/freckles/cmd/init.go:flagcompletion}}

docs/src/freckles/cmd/root.md

@@ -18,7 +18,7 @@
 
 ## Gen
 
-[Gen] adds a hidden `_carapace` subcommand which handles [script](#script) generation, [completions](#export), and [macros](#macro).
+[Gen] adds a hidden `_carapace` subcommand which handles [script](#script) generation, completion [export](#export), and [macros](#macro).
 
 ```go
 {{#include ../../../../cmd/freckles/cmd/root.go:gen}}
@@ -70,7 +70,7 @@ freckles _carapace export freckles [ARGS]...
 > This has several benefits:
 > - it avoids the [startup delay] issue
 > - it provides a central registration point for all shells
-> - it enables [embedding] with [`bridge.ActionCarapaceBin`]
+> - it enables [embedding] with [`ActionCarapaceBin`]
 > - it uses the newest version of [Carapace] for shell integration
 
 ## Macro
@@ -88,7 +88,7 @@ freckles _carapace export freckles [ARGS]...
 > More on this at [Init#Clone](./init.md#clone) and [Edit#Action](./edit.md#action).
 
 [#1336]:https://github.com/carapace-sh/carapace-bin/issues/1336
-[`bridge.ActionCarapaceBin`]:https://pkg.go.dev/github.com/carapace-sh/carapace-bridge/pkg/actions/bridge#ActionCarapaceBin
+[`ActionCarapaceBin`]:https://pkg.go.dev/github.com/carapace-sh/carapace-bridge/pkg/actions/bridge#ActionCarapaceBin
 [Actions]:https://carapace-sh.github.io/carapace/carapace/action.html
 [Carapace]:https://carapace.sh
 [Cobra]:https://github.com/spf13/cobra