Merge pull request #1091 from SierraSoftworks/dependabot/npm_and_yarn…

…/docs/vuepress-8c43da3354

chore(deps-dev): bump the vuepress group in /docs with 4 updates

.github/workflows/docs-website.yml

@@ -12,27 +12,49 @@ on:
       - docs/**/*
 
 jobs:
+  build:
+    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
+    runs-on: ubuntu-latest
+    name: Build (Docs)
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 'lts/*'
+      - name: Install Dependencies
+        run: cd docs && npm ci
+      - name: Build
+        run: cd docs && npm run build
+      - name: Upload Artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: docs/.vuepress/dist
+
   deploy:
     if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
     runs-on: ubuntu-latest
-    name: Build and Deploy
+    needs: build
+    name: Deploy to Azure Static Web Apps
     steps:
-      - uses: actions/checkout@v4
+      - name: Download Artifact
+        uses: actions/download-artifact@v4
         with:
-          submodules: true
-      - name: Build And Deploy
+          name: docs
+          path: dist
+
+      - name: Deploy
         id: builddeploy
         uses: Azure/static-web-apps-deploy@v1
         with:
           azure_static_web_apps_api_token: ${{ secrets.AZURE_WEBSITES_TOKEN }}
           repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
           action: "upload"
-          ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
-          # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
-          app_location: "/docs" # App source code path
-          api_location: "" # Api source code path - optional
-          output_location: ".vuepress/dist" # Built app content directory - optional
-          ###### End of Repository/Build Configurations ######
+          app_location: "/dist"
+          api_location: ""
+          skip_app_build: true
 
   cleanup:
     if: github.event_name == 'pull_request' && github.event.action == 'closed'

docs/commands/setup.md

@@ -1,24 +1,25 @@
 # Setup
 
 ## update <Badge text="v1.4+"/>
-We like to think that we're pretty good at updating Git-Tool to ensure that
-it is using the latest stable libraries and includes all the best features.
-Of course, that also means some pretty regular releases (usually once every
-week or two) and for a command line application, that can mean that things
-get outdated pretty quickly.
+
+We like to think that we're pretty good at updating Git-Tool to ensure that it
+is using the latest stable libraries and includes all the best features. Of
+course, that also means some pretty regular releases (usually once every week or
+two) and for a command line application, that can mean that things get outdated
+pretty quickly.
 
 To help with that, we added the `gt update` command which will automatically
-download the latest version of Git-Tool for your operating system (if we
-support it in our release builds).
-
-::: warning
-We use an [three-phase update strategy][update-strategy] for Git-Tool and,
-as a result, we can't update it if other instances are currently running.
-**To make sure the update completes successfully, close down all running
-instances of Git-Tool (including shells it has launched) before updating.**
-:::
+download the latest version of Git-Tool for your operating system (if we support
+it in our release builds).
+
+::: warning We use an [three-phase update strategy][update-strategy] for
+Git-Tool and, as a result, we can't update it if other instances are currently
+running. **To make sure the update completes successfully, close down all
+running instances of Git-Tool (including shells it has launched) before
+updating.** :::
 
 #### Example
+
 ```powershell
 # Update to the latest available release for your OS
 gt update
@@ -28,69 +29,78 @@ gt update v2.2.0
 ```
 
 ## shell-init <Badge text="v1.5+"/>
+
 The `gt shell-init` command is part of the magic that provides cross-platform
 autocomplete suggestions and lets us upgrade our infrastructure for that
 automatically.
 
 It is responsible for generating a runnable shell command which initializes
 everything needed by Git-Tool for your environment.
 
-::: tip
-Take a look at the [shell setup guide](../guide/shell-init.md) for detailed
-instructions on setting up your shell environment to get the most out of
-Git-Tool.
-:::
+::: tip Take a look at the [shell setup guide](../guide/installation.md) for
+detailed instructions on setting up your shell environment to get the most out
+of Git-Tool. :::
 
 #### Example
-:::: code-group
-::: code-group-item PowerShell
+
+:::: code-group ::: code-group-item PowerShell
+
 ```powershell
 # $PROFILE.CurrentUserAllHosts
 Invoke-Expression (&git-tool shell-init powershell)
 ```
+
 :::
 
 ::: code-group-item bash
+
 ```bash
 # ~/.bashrc
 eval "$(git-tool shell-init bash)"
 ```
+
 :::
 
 ::: code-group-item zsh
+
 ```bash
 # ~/.zshrc
 eval "$(git-tool shell-init zsh)"
 ```
+
 :::
 
 ::: code-group-item fish
+
 ```bash
 # ~/config.fish
 complete -f -c git-tool -a "(git-tool complete)"
 ```
-:::
-::::
+
+::: ::::
 
 ## complete <Badge text="v1.2+"/> <Badge text="internal" type="warning"/>
-The `gt complete` command is part of the internal autocomplete plumbing
-used by Git-Tool. It is a flagrant copy of the
+
+The `gt complete` command is part of the internal autocomplete plumbing used by
+Git-Tool. It is a flagrant copy of the
 [dotnet CLI autocomplete](https://docs.microsoft.com/en-us/dotnet/core/tools/enable-tab-autocomplete)
 interface and accepts a combination of the current command input and the
 position of the cursor (if provided) to generate suggestions.
 
-::: warning
-This command is part of Git-Tool's internal API and may change without notice and without
-a major version bump. Please avoid depending on its semantics and instead use `gt shell-init`
-to configure your environment.
-:::
+::: warning This command is part of Git-Tool's internal API and may change
+without notice and without a major version bump. Please avoid depending on its
+semantics and instead use `gt shell-init` to configure your environment. :::
 
 #### Options
- - `--position` allows a shell which supports this parameter to provide information about the current cursor position to improve autocomplete suggestion quality.
+
+- `--position` allows a shell which supports this parameter to provide
+  information about the current cursor position to improve autocomplete
+  suggestion quality.
 
 #### Example
+
 ```powershell
 gt complete "gt o git-too"
 ```
 
-[update-strategy]: https://blog.sierrasoftworks.com/2019/10/15/app-updates/
+[update-strategy]: https://blog.sierrasoftworks.com/2019/10/15/app-updates/

docs/config/features.md

@@ -1,107 +1,120 @@
 # Features
-In some situations you may want finer grained control over the way Git Tool behaves. This is accomplished through
-the Git Tool configuration file and some of its advanced options.
+
+In some situations you may want finer grained control over the way Git Tool
+behaves. This is accomplished through the Git Tool configuration file and some
+of its advanced options.
 
 ## `http_transport` <Badge text="v1.2.19+"/> <Badge text="v3.x" type="warning" />
-  - **Default** `false`
 
-::: warning
-This feature flag is not supported in Git-Tool `v3.x`, with this behaviour being controlled by the [`gitUrl`](./services.md#giturl) service field.
-:::
+- **Default** `false`
+
+::: warning This feature flag is not supported in Git-Tool `v3.x`, with this
+behaviour being controlled by the [`gitUrl`](./services.md#giturl) service
+field. :::
 
-By default Git-Tool uses the SSH transport for `git` with URLs like `[email protected]:sierrasoftworks/git-tool.git`.
-In some situations, particularly those where you wish to run without authentication, you may prefer to use git's HTTPS transport
-instead.
+By default Git-Tool uses the SSH transport for `git` with URLs like
+`[email protected]:sierrasoftworks/git-tool.git`. In some situations, particularly
+those where you wish to run without authentication, you may prefer to use git's
+HTTPS transport instead.
 
-::: tip
-Use `gt config feature http_transport true` to turn this flag on directly from your command line.
-:::
+::: tip Use `gt config feature http_transport true` to turn this flag on
+directly from your command line. :::
 
 ## `create_remote` <Badge text="v1.0+"/>
- - **Default** `true`
 
-Git-Tool will, if this feature is enabled and the `--no-create-remote` option is not specified, attempt to create
-a remote repository on your hosting provider for recognized services when running `gt new`. This can be helpful
-for users who don't want to manually set up a GitHub repo - but you can disable it if you prefer.
+- **Default** `true`
+
+Git-Tool will, if this feature is enabled and the `--no-create-remote` option is
+not specified, attempt to create a remote repository on your hosting provider
+for recognized services when running `gt new`. This can be helpful for users who
+don't want to manually set up a GitHub repo - but you can disable it if you
+prefer.
 
-::: tip
-Use `gt config feature create_remote false` to turn this flag off directly from your command line.
-:::
+::: tip Use `gt config feature create_remote false` to turn this flag off
+directly from your command line. :::
 
 ## `create_remote_private` <Badge text="v2.0+"/>
- - **Default** `true`
 
-When creating a remote repository with `gt n` and the [`create_remote`](#create-remote) feature enabled,
-Git-Tool will (by default) create a *Private* repo (if your service supports it). You can usually convert
-a Private repository to a Public one when you're ready, however if you would prefer to create Public repos,
-you can disable this feature flag.
+- **Default** `true`
 
-::: tip
-Use `gt config feature create_remote_private false` to turn this flag off directly from your command line.
-:::
+When creating a remote repository with `gt n` and the
+[`create_remote`](#create-remote) feature enabled, Git-Tool will (by default)
+create a _Private_ repo (if your service supports it). You can usually convert a
+Private repository to a Public one when you're ready, however if you would
+prefer to create Public repos, you can disable this feature flag.
+
+::: tip Use `gt config feature create_remote_private false` to turn this flag
+off directly from your command line. :::
 
 ## `check_exists` <Badge text="v3.3+"/>
-  - **Default** `true`
-  
-The [`gt new`](../commands/new.md) command is responsible for creating repositories which do not exist yet.
-Unfortunately, sometimes people forget that they've already created one with the same name and this can lead
-to unexpected conflicts. To help avoid this, Git-Tool can check whether a repository already exists on a
-supported remote service before attempting to create a new one.
-
-::: tip
-Use `gt config feature check_exists false` to turn this flag off directly from your command line.
-:::
-
-::: warning
-This feature is not supported for all services. For a service to support this feature it must include
-a supported [`api`](./services.md#api) field in its configuration.
-:::
+
+- **Default** `true`
+
+The [`gt new`](../commands/repos.md) command is responsible for creating
+repositories which do not exist yet. Unfortunately, sometimes people forget that
+they've already created one with the same name and this can lead to unexpected
+conflicts. To help avoid this, Git-Tool can check whether a repository already
+exists on a supported remote service before attempting to create a new one.
+
+::: tip Use `gt config feature check_exists false` to turn this flag off
+directly from your command line. :::
+
+::: warning This feature is not supported for all services. For a service to
+support this feature it must include a supported [`api`](./services.md#api)
+field in its configuration. :::
 
 ## `open_new_repo_in_default_app` <Badge text="v2.1.1+"/>
- - **Default** `false`
 
-When this feature flag is enabled, Git-Tool will automatically open newly created repositories in your
-default application when running `gt new`. This is equivalent to passing the `--open` flag.
+- **Default** `false`
+
+When this feature flag is enabled, Git-Tool will automatically open newly
+created repositories in your default application when running `gt new`. This is
+equivalent to passing the `--open` flag.
 
-::: tip
-Use `gt config feature open_new_repo_in_default_app true` to turn this flag on directly from your command line.
-:::
+::: tip Use `gt config feature open_new_repo_in_default_app true` to turn this
+flag on directly from your command line. :::
 
 ## `always_open_best_match` <Badge text="v3.2+"/>
 
-When this feature flag is enabled, Git-Tool will always open the best matching repository if there are
-multiple repositories which may be matched by your current pattern.
+When this feature flag is enabled, Git-Tool will always open the best matching
+repository if there are multiple repositories which may be matched by your
+current pattern.
 
-:::
-Use `gt config feature always_open_best_match true` to turn this flag on directly from your command line.
-:::
+::: Use `gt config feature always_open_best_match true` to turn this flag on
+directly from your command line. :::
 
 ## `telemetry` <Badge text="v2.1.21+"/>
- - **Default** `false`
 
-Git-Tool can send limited telemetry to [Sentry.io](https://sentry.io) and [Honeycomb](https://honeycomb.io) 
-to try and help us figure out the cause of crashes and improve the tool for everyone. If you would like to
-share your telemetry with us, you can enable this feature flag.
+- **Default** `false`
 
-::: tip
-Use `gt config feature telemetry true` to turn this flag on directly from your command line.
-:::
+Git-Tool can send limited telemetry to [Sentry.io](https://sentry.io) and
+[Honeycomb](https://honeycomb.io) to try and help us figure out the cause of
+crashes and improve the tool for everyone. If you would like to share your
+telemetry with us, you can enable this feature flag.
+
+::: tip Use `gt config feature telemetry true` to turn this flag on directly
+from your command line. :::
 
 ## `check_for_updates` <Badge text="v3.2+"/>
-  - **Default** `true`
 
-Git-Tool receives regular updates and includes a built in [`gt update`](./commands/setup.md#update) command
-which you can use to update to the latest version. This feature flag controls whether Git-Tool will check
-for new updates when you open a repository and let you know about them when you exit it. This model is
-designed to avoid any latency penalties, while keeping you up to date with the latest updates.
+- **Default** `true`
+
+Git-Tool receives regular updates and includes a built in
+[`gt update`](../commands/setup.md#update) command which you can use to update
+to the latest version. This feature flag controls whether Git-Tool will check
+for new updates when you open a repository and let you know about them when you
+exit it. This model is designed to avoid any latency penalties, while keeping
+you up to date with the latest updates.
 
 ## `native_clone` <Badge text="v1.2.18+" /> <Badge text="v2.0+" type="warning"/>
- - **Default** `false`
 
-::: warning
-This feature flag is not supported in Git-Tool `v2.x`, with this behaviour being the default in all newer versions of Git-Tool.
-:::
+- **Default** `false`
+
+::: warning This feature flag is not supported in Git-Tool `v2.x`, with this
+behaviour being the default in all newer versions of Git-Tool. :::
 
-Git-Tool supports using your local `git` executable to clone and initialize repositories instead of using its built-in git logic.
-If you wish to use your local `git` executable, set this feature to `true` in your config. Doing so may resolve
-issues with smart-card/YubiKey authentication, or with SSH-Agent on Windows.
+Git-Tool supports using your local `git` executable to clone and initialize
+repositories instead of using its built-in git logic. If you wish to use your
+local `git` executable, set this feature to `true` in your config. Doing so may
+resolve issues with smart-card/YubiKey authentication, or with SSH-Agent on
+Windows.