[website] Add pages for CLI commands

apps/sparo-lib/src/cli/commands/ci-checkout.ts

@@ -13,7 +13,7 @@ export interface ICICheckoutCommandOptions {
 export class CICheckoutCommand implements ICommand<ICICheckoutCommandOptions> {
   public cmd: string = 'checkout';
   public description: string =
-    'Special checkout command for CI. It only accepts project selector suchs as --to and --from now.';
+    'Special checkout command for CI. It only accepts project selector such as --to and --from now.';
   @inject(GitSparseCheckoutService) private _gitSparseCheckoutService!: GitSparseCheckoutService;
   public builder(yargs: Argv<ICICheckoutCommandOptions>): void {
     yargs

apps/website/docs/index.md

@@ -16,12 +16,7 @@ import { ThemedImage } from '@site/src/components/ThemedImage';
     />
 </div>
 
-> 🚧 UNDER CONSTRUCTION 🚧
->
-> This is an early test release of the software.
-> It is not yet ready for general usage.
-> If you have questions about this project, let us know
-> using [GitHub discussions](https://github.com/tiktok/sparo/discussions).
+
 
 ## Clone faster!
 

apps/website/docs/pages/ci_commands/overview.md

@@ -0,0 +1,19 @@
+---
+title: Overview
+---
+
+Everyday development involves a variety of Git operations such as switching between branches, fetching incremental changes from the server, and browsing history.  By contrast, when a continuous integration (CI) pipeline checks out a Git branch, it is typically a much simpler operation. The folder or entire virtual machine image may be discarded as soon as the job completes.  Therefore, different approaches for optimizing Git require required for these two use cases.
+
+Sparo provides a separate command line `sparo-ci` that is specifically optimized for CI pipelines.  The current implementation takes this approach:
+
+- It uses [treeless clone](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/) instead of **blobless clone**, under the assumption that Git history will be rarely needed.
+
+  _Shallow clone is a common alternative, however it has trouble supporting operations such as incremental build or publishing that require comparison with a base branch._
+
+- Sparse checkout is configured, and the [skeleton folders](../reference/skeleton_folders.md) are included.
+
+Currently two subcommands are supported for CI:
+
+- `sparo-ci checkout`
+- `sparo-ci clone`
+

apps/website/docs/pages/ci_commands/sparo-ci_checkout.md

@@ -0,0 +1,17 @@
+---
+title: sparo-ci checkout
+---
+
+```
+sparo-ci checkout
+
+Special checkout command for CI. It only accepts project selector such as --to
+and --from now.
+
+Options:
+      --help  Show help                                                [boolean]
+  -t, --to    See https://rushjs.io/pages/developer/selecting_subsets/#--to for
+              more details.                                              [array]
+  -f, --from  See https://rushjs.io/pages/developer/selecting_subsets/#--from
+              for more details.                                          [array]
+```

apps/website/docs/pages/ci_commands/sparo-ci_clone.md

@@ -0,0 +1,18 @@
+---
+title: sparo-ci clone
+---
+
+```
+sparo-ci clone <repository> [directory]
+
+Positionals:
+  repository  The remote repository to clone from.           [string] [required]
+  directory   The name of a new directory to clone into. The "humanish" part of
+              the source repository is used if no directory is explicitly given
+              (repo for /path/to/repo.gitService and foo for
+              host.xz:foo/.gitService). Cloning into an existing directory is
+              only allowed if the directory is empty                    [string]
+
+Options:
+  --help  Show help                                                    [boolean]
+```

apps/website/docs/pages/commands/overview.md

@@ -9,25 +9,27 @@ Sparo has four kinds of subcommands:
 1. **Mirrored subcommands** such as `sparo branch` and `sparo revert` directly invoke the corresponding `git` version of that subcommand.  The motivation for using mirrored subcommands is to enable Sparo to provide advice about parameters that may cause performance issues.  Additionally, you can optionally configure Sparo to collect anonymized usage metrics to help you measure the experience in your repository.  (Collected data is sent to your own service. It is not accessible by any other party.)
 
 2. **Enhanced subcommands** follow the same basic design as their `git` counterparts, but with adaptations for sparse checkout profiles and more efficient defaults.  There are four enhanced commands:
-   - `sparo clone`
    - `sparo checkout`
+   - `sparo clone`
    - `sparo fetch`
-   - `sparo pull`
+   - `sparo pull` _(not implemented yet; currently mirrors `git pull`)_
 
 3. **Renamed subcommands** are the mirrored versions of the four enhanced subcommands. They are renamed to add a `git-` prefix:
-  - `sparo git-clone`
   - `sparo git-checkout`
+  - `sparo git-clone`
   - `sparo git-fetch`
-  - `sparo git-pull`.
+  - `sparo git-pull` _(not implemented yet)_
 
 4. **Auxiliary subcommands** are new subcommands that provide Sparo-specific functionality.  They are:
-  - `sparo purge`
-  - `sparo list-profiles`
+  - `sparo auto-config`
   - `sparo init-profile`
+  - `sparo list-profiles`
+  - `sparo inspect` _(not implemented yet, will report working directory status and diagnostics)_
+  - `sparo reclone` _(not implemented yet, will efficiently revert to a clean clone)_
 
 ## Mirrored commands
 
-Each subcommand has its own page in this documentation, except for the mirrored commands which are already covered by the Git documentation.  For convenience, their names are listed in the table below.
+Each subcommand has its own page in this documentation, except for the mirrored commands which are already covered by the Git documentation.  For convenience, the most essential ["porcelain"](https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain) subcommands are listed in the table below, however every Git subcommand is supported.
 
 | Subcommand | Summary |
 | --- | --- |
@@ -71,4 +73,8 @@ Each subcommand has its own page in this documentation, except for the mirrored
 | [git stash](https://git-scm.com/docs/git-stash) | Stash the changes in a dirty working directory away |
 | [git status](https://git-scm.com/docs/git-status) | Show the working tree status |
 | [git submodule](https://git-scm.com/docs/git-submodule) | Initialize, update or inspect submodules |
-| [git switch](https://git-scm.com/docs/git-switch) |
+| [git switch](https://git-scm.com/docs/git-switch) | Switch branches |
+| [git tag](https://git-scm.com/docs/git-tag) | Create, list, delete or verify a tag object signed with GPG |
+| [git worktree](https://git-scm.com/docs/git-worktree) | Manage multiple working trees |
+| . . . | _...and many other subcommands including any custom commands found in the shell `PATH`_ |
+

apps/website/docs/pages/commands/sparo_auto-config.md

@@ -0,0 +1,34 @@
+---
+title: sparo auto-config
+---
+
+```
+sparo auto-config
+
+Automatic setup optimized git config
+
+Options:
+  --help       Show help                                               [boolean]
+  --overwrite                                         [boolean] [default: false]
+```
+
+You do not normally need to invoke `sparo auto-config`.  As the name implies, it is automatically applied by `sparo clone`.  This command is provided for reapplying the configuration in a situation where the user may have manually altered Sparo's configuration.  It is a good first step when investigating problems.
+
+## Auto-config settings
+
+The implementation can be found in [GitService.ts](https://github.com/tiktok/sparo/blob/main/apps/sparo-lib/src/services/GitService.ts).  Below is a summary of the currently applied settings:
+
+```
+pull.rebase=true
+fetch.prune=true
+fetch.showForcedUpdates=false
+feature.manyFiles=true
+core.fsmonitor=true
+core.fscache=true
+core.untrackedcache=true
+om-my-zsh.hide-status=1
+on-my-zsh.hide-dirty=1
+lfs.allowincompletepush=true
+lfs.concurrenttransfers=32
+push.autoSetupRemote=true
+```

apps/website/docs/pages/commands/sparo_checkout.md

@@ -0,0 +1,23 @@
+---
+title: sparo checkout
+---
+
+```
+sparo checkout [branch] [start-point]
+
+Updates files in the working tree to match the version in the index or the
+specified tree. If no pathspec was given, git checkout will also update HEAD to
+set the specified branch as the current branch.
+
+Positionals:
+  branch                                                                [string]
+  start-point                                                           [string]
+
+Options:
+      --help         Show help                                         [boolean]
+  -b                 Create a new branch and start it at <start-point> [boolean]
+  -B                 Create a new branch and start it at <start-point>; if it
+                     already exists, reset it to <start-point>         [boolean]
+      --profile                                            [array] [default: []]
+      --add-profile                                        [array] [default: []]
+```

apps/website/docs/pages/commands/sparo_clone.md

@@ -0,0 +1,24 @@
+---
+title: sparo clone
+---
+
+```
+sparo clone <repository> [directory]
+
+Positionals:
+  repository  The remote repository to clone from.           [string] [required]
+  directory   The name of a new directory to clone into. The "humanish" part of
+              the source repository is used if no directory is explicitly given
+              (repo for /path/to/repo.gitService and foo for
+              host.xz:foo/.gitService). Cloning into an existing directory is
+              only allowed if the directory is empty                    [string]
+
+Options:
+      --help             Show help                                     [boolean]
+  -s, --skip-git-config  By default, Sparo automatically configures the
+                         recommended git settings for the repository you are
+                         about to clone. If you prefer not to include this step,
+                         you can use the input parameter --skip-git-config
+                                                      [boolean] [default: false]
+  -b, --branch           Specify a branch to clone                      [string]
+```

apps/website/docs/pages/commands/sparo_fetch.md

@@ -0,0 +1,16 @@
+---
+title: sparo fetch
+---
+
+```
+sparo fetch [remote] [branch]
+
+fetch remote branch to local
+
+Positionals:
+  remote                                                                [string]
+  branch                                                                [string]
+
+Options:
+  --help  Show help                                                    [boolean]
+```

apps/website/docs/pages/commands/sparo_git-checkout.md

@@ -0,0 +1,17 @@
+---
+title: sparo git-checkout
+---
+
+This is the [mirrored subcommand](./overview.md) for `git checkout`.  It has the same functionality as the corresponding Git subcommand, but supports Sparo's optional anonymous timing metrics collection.
+
+```
+sparo git-checkout [-q] [-f] [-m] [<branch>]
+sparo git-checkout [-q] [-f] [-m] --detach [<branch>]
+sparo git-checkout [-q] [-f] [-m] [--detach] <commit>
+sparo git-checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]
+sparo git-checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>…​
+sparo git-checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]
+sparo git-checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>…​]
+```
+
+See [git checkout](https://git-scm.com/docs/git-checkout) in the Git documentation for details.

apps/website/docs/pages/commands/sparo_git-clone.md

@@ -0,0 +1,19 @@
+---
+title: sparo git-clone
+---
+
+This is the [mirrored subcommand](./overview.md) for `git clone`.  It has the same functionality as the corresponding Git subcommand, but supports Sparo's optional anonymous timing metrics collection.
+
+```
+sparo git-clone [--template=<template-directory>]
+	  [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]
+	  [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]
+	  [--dissociate] [--separate-git-dir <git-dir>]
+	  [--depth <depth>] [--[no-]single-branch] [--no-tags]
+	  [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]
+	  [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]
+	  [--filter=<filter> [--also-filter-submodules]] [--] <repository>
+	  [<directory>]
+```
+
+See [git clone](https://git-scm.com/docs/git-clone) in the Git documentation for details.

apps/website/docs/pages/commands/sparo_git-fetch.md

@@ -0,0 +1,15 @@
+---
+title: sparo git-fetch
+---
+
+This is the [mirrored subcommand](./overview.md) for `git fetch`.  It has the same functionality as the corresponding Git subcommand, but supports Sparo's optional anonymous timing metrics collection.
+
+```
+sparo git-fetch [<options>] [<repository> [<refspec>…​]]
+sparo git-fetch [<options>] <group>
+sparo git-fetch --multiple [<options>] [(<repository> | <group>)…​]
+sparo git-fetch --all [<options>]
+```
+
+See [git fetch](https://git-scm.com/docs/git-fetch) in the Git documentation for details.
+

apps/website/docs/pages/commands/sparo_init-profile.md

@@ -0,0 +1,13 @@
+---
+title: sparo init-profile
+---
+
+```
+sparo init-profile
+
+Initialize a new profile.
+
+Options:
+  --help     Show help                                                 [boolean]
+  --profile  The name of the profile to initialize.          [string] [required]
+```

apps/website/docs/pages/commands/sparo_list-profiles.md

@@ -0,0 +1,14 @@
+---
+title: sparo list-profiles
+---
+
+```
+sparo list-profiles
+
+List all available profiles or query profiles that contain the specified project
+name
+
+Options:
+  --help     Show help                                                 [boolean]
+  --project  List all profiles contains this specified project name     [string]
+```