Editing

apps/website/README.md

@@ -6,14 +6,14 @@ This is the [Docusaurus](https://docusaurus.io/) project for the Sparo website.
 
 1. Install the monorepo dependencies using [RushJS](https://rushjs.io/):
 
-   ```shell
+   ```bash
    rush install
    rush build
    ```
 
 2. Launch the local development server:
 
-   ```shell
+   ```bash
    cd apps/website
    rushx start
    ```
@@ -33,14 +33,14 @@ Notes:
 
 1. If you will manually copy the files to a server, you can build the **apps/sparo/build** folder like this:
 
-   ```shell
+   ```bash
    cd apps/website
    rushx build
    ```
 
 2. To automatically deploy to GitHub Pages (as an administrator):
 
-   ```shell
+   ```bash
    # If you are using HTTPS authentication for GitHub:
    cd apps/website
    GIT_USER=<Your GitHub username> rushx deploy

apps/website/docs/index.md

@@ -48,7 +48,7 @@ Try out Sparo in 5 easy steps:
 
 2. Clone your [RushJS](https://rushjs.io/) monorepo:
 
-   ```shell
+   ```bash
    sparo clone https://github.com/my-company/my-monorepo.git
    ```
 
@@ -76,15 +76,15 @@ Try out Sparo in 5 easy steps:
 
 4. Check out your Sparo profile:
 
-   ```shell
+   ```bash
    sparo checkout --profile my-team
    ```
 
 5. For everyday work, consider choosing [mirrored subcommands](./pages/commands/overview.md) such as `sparo revert` instead of `git revert`. The Sparo wrapper provides (1) better defaults, (2) suggestions for better performance, and (3) optional anonymized performance metrics.
 
    Examples:
 
-   ```shell
+   ```bash
    sparo pull
 
    sparo commit -m "Example command"

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

@@ -2,15 +2,15 @@
 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, and 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.
+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._
 
-- Spare checkout is configured, and the [skeleton folders](../reference/skeleton_folders.md) are included.
+- Sparse checkout is configured, and the [skeleton folders](../reference/skeleton_folders.md) are included.
 
 Currently two subcommands are supported for CI:
 

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

@@ -12,20 +12,20 @@ Sparo has four kinds of subcommands:
    - `sparo checkout`
    - `sparo clone`
    - `sparo fetch`
-   - `sparo pull` (not implemented yet; currently mirrors `git 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-checkout`
   - `sparo git-clone`
   - `sparo git-fetch`
-  - `sparo git-pull` (not implemented yet)
+  - `sparo git-pull` _(not implemented yet)_
 
 4. **Auxiliary subcommands** are new subcommands that provide Sparo-specific functionality.  They are:
   - `sparo auto-config`
   - `sparo init-profile`
   - `sparo list-profiles`
-  - `sparo inspect` (not implemented yet, reports working directory status and diagnostics)
-  - `sparo reclone` (not implemented yet, will efficiently revert to a clean clone)
+  - `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
 

apps/website/docs/pages/guide/getting_started.md

@@ -19,7 +19,7 @@ Many Git optimizations are relatively new and not available in older versions of
 
 Clone your [RushJS](https://rushjs.io/) monorepo:
 
-```shell
+```bash
 sparo clone https://github.com/my-company/my-monorepo.git
 ```
 
@@ -64,7 +64,7 @@ The `--to` [project selector](https://rushjs.io/pages/developer/selecting_subset
 The `--profile` parameter can be included with `sparo checkout` (and in the future also `sparo clone` and `sparo pull`).  This parameter specifies the name of the JSON file to be selected.  You can also combine multiple profiles (`sparo checkout --profile p1 --profile p2`), in which case the union of their selections will be used.  (Combining profiles is an advanced scenario, but useful for example if your pull request will impact sets of projects belonging to multiple teams.)
 
 **Sparse checkout based on common/sparo-profiles/my-team.json**
-```shell
+```bash
 sparo checkout --profile my-team
 ```
 
@@ -75,7 +75,7 @@ sparo checkout --profile my-team
 - To checkout just the skeleton (returning to the initial state from Step 1 where no profile is chosen yet), specify `--no-profile` instead of `--profile NAME`.
 
 - To add more profiles, combining with your existing selection, use `--add-profile NAME` instead of `--profile NAME`.  For example, these two commands produce the same result as `sparo checkout --profile p1 --profile p2`:
-  ```shell
+  ```bash
   sparo checkout --profile p1
   sparo checkout --add-profile p2
   ```
@@ -86,7 +86,7 @@ For everyday work, consider choosing [mirrored subcommands](../commands/overview
 
 Examples:
 
-```shell
+```bash
 sparo pull
 
 sparo commit -m "Example command"

apps/website/docs/pages/guide/sparo_profiles.md

@@ -2,7 +2,7 @@
 title: Sparo profiles
 ---
 
-Git's sparse checkout feature normally relies on a collection of glob patterns that are stored in the `.git/info/sparse-checkout` config file.  Normal glob syntax proved to be too inefficient, so Git instead uses ["cone mode"](https://git-scm.com/docs/git-sparse-checkout#_internalsnon_cone_problems) that ignores file-matching patterns and only matches directories.
+Git's sparse checkout feature normally relies on a collection of glob patterns that are stored in the `.git/info/sparse-checkout` config file.  Normal glob syntax proved to be too inefficient, so Git instead uses a ["cone mode"](https://git-scm.com/docs/git-sparse-checkout#_internalsnon_cone_problems) glob interpretation that ignores file-matching patterns and only matches directories.
 
 The syntax looks something like this:
 
@@ -17,19 +17,19 @@ The syntax looks something like this:
 /apps/my-app/_/
 ```
 
-To simplify management, the `git sparse-checkout` command line provides convenient ways to add/remove patterns from this file.  However, in a large monorepo with hundreds of projects, managing these globs can be confusing and error-prone.
+To simplify management, the `git sparse-checkout` command line provides convenient ways to add/remove patterns from this file.  However, in a large monorepo with hundreds of projects, managing these globs would nonetheless be confusing and error-prone.
 
-Sparo's approach is to generate the `.git/info/sparse-checkout` configuration from config files called profiles.  This provides many benefits:
+Sparo makes life easier by generating the `.git/info/sparse-checkout` configuration automatically from config files called **profiles.**  This offers many benefits:
 
-- Profiles are specified using [project selectors](https://rushjs.io/pages/developer/selecting_subsets/#--to), for example: _"Give me **app1**, **app2**, and all the projects needed to build them."_ This is more concise and maintainable than specifying globs.
+- Sparo profiles are defined using [project selectors](https://rushjs.io/pages/developer/selecting_subsets/#--to), for example: _"Give me **app1**, **app2**, and all the projects needed to build them."_ This is more concise and maintainable than specifying globs.
 
 - Profiles are stored in a config file and committed to Git.  This makes it easy to share them with your teammates.
 
 - Profiles are automatically updated when switching between branches, which ensures deterministic results.  For example, when checking out a very old branch, you want the old profile definition, not today's version of it.
 
-- You combine multiple profiles at the same time (`sparo checkout --profile team1 --profile team2`), which produces the union of their subsets.  This is useful for example when modifying a library project that is consumed by projects belonging to several other teams.  You could instead use a selector `--from the-library` of course, but it's likely those other teams have included other relevant projects in their profiles.
+- You can combine multiple profiles together (`sparo checkout --profile team1 --profile team2`), which selects the union of their projects.  This is useful for example when modifying a library project that is consumed by projects belonging to several other teams.  You could check out their projects using `--from the-library` of course, but it's likely those other teams will have included other relevant projects in their profiles.
 
-- Sparo avoids common mistakes by imposing additional restrictions beyond `git sparse-checkout`.
+- Sparo avoids common mistakes by imposing additional restrictions beyond `git sparse-checkout`.  This avoids mistakes such as trying to switch to a profile that is missing a project folder containing files that are locally modified. It is better for users to stash or commit such modifications first.
 
 ## Best practices for profiles
 
@@ -67,24 +67,24 @@ You an add JSON comments to your profile config files.  In a large shared codeba
 
 The simple way to combine profiles is to specify `--profile` multiple times.  For example:
 
-```shell
+```bash
 # Check out the union of profiles team-a.json, team-b.json, team-c.json
 # NOTE: This will replace whatever profile selection was already checked out.
 sparo checkout --profile team-a --profile team-b --profile team-c
 ```
 
 You can also use `--add-profile` to incrementally combine them.  For example:
 
-```shell
+```bash
 # These three commands are equivalent to the above command.
 sparo checkout --profile team-a
 sparo checkout --add-profile team-b
 sparo checkout --add-profile team-c
 ```
 
-How to checkout NO profile? In other words, returning to the [skeleton](../reference/skeleton_folders.md) state of a clean `sparo clone`?  It can't be `sparo checkout`, because if `--profile` is entirely omitted then the existing profile selection is preserved.
+How to checkout no profile at all? That is, how to return to the initial state of a clean `sparo clone` that only includes the [skeleton](../reference/skeleton_folders.md) folders?  If `--profile` is entirely omitted, then `sparo checkout` will preserve the existing profile selection.  Instead, the `--no-profile` parameter is needed:
 
-```shell
+```bash
 # NOT IMPLEMENTED YET - check out just the skeleton folders
 # without applying any profiles
 sparo checkout --no-profile
@@ -93,9 +93,9 @@ sparo checkout --no-profile
 
 ## Querying profiles
 
-Engineers can find available profiles in the current branch by invoking the [sparo list-profiles](../commands/sparo_list-profiles) command.  The `--project` parameter enables you to query relevant profiles for a given project.  For example:
+Users can discover available profiles in the current branch by invoking the [sparo list-profiles](../commands/sparo_list-profiles) command.  The `--project` parameter enables you to query relevant profiles for a given project.  For example:
 
-```shell
+```bash
 # Suppose you need to make a fix for the "example-app" project.
 
 # Which sparse checkout profiles include the "example-app" project?

apps/website/docs/pages/reference/security.md

@@ -5,7 +5,7 @@ title: Security
 Because the Sparo tool acts as a wrapper for Git, our goal is to provide comparable security expectations as the `git` command.
 
 > ⚠️ **This is a goal not a guarantee.** ⚠️
-> 
+>
 > The software is still in its early stages of development, and not all security
 > requirements have been identified or implemented yet.  Efforts to improve Sparo
 > security should not be interpreted to contradict the terms of the MIT license:
@@ -48,15 +48,15 @@ And of course, if an explicit target folder is specified using `git clone https:
 
 Shell interpreters commonly transform expressions involving special characters such as `$`, `%`, `(`, etc.  For example:
 
-```shell
-# Problem: Bash would replace "$project" with the value of 
+```bash
+# Problem: Bash would replace "$project" with the value of
 # the environment variable whose name is "project".
 git clone https://github.com/example/project.git $project
 ```
 
 This requires escaping:
 
-```shell
+```bash
 # This backslash escape ensures that a literal dollar sign
 # is included in the created folder name:
 git clone https://github.com/example/project.git \$project

apps/website/docs/pages/support/contributing.md

@@ -6,32 +6,32 @@ Building the projects in this monorepo:
 
 1. Install the [RushJS](https://rushjs.io/) tool:
 
-   ```shell
+   ```bash
    npm install -g @microsoft/rush
    ```
 
 2. Clone the repo:
 
-   ```shell
+   ```bash
    git clone https://github.com/tiktok/sparo.git
    ```
 
 3. Install the dependencies
 
-   ```shell
+   ```bash
    cd sparo
    rush install
    ```
 
 4. Build all projects
 
-   ```shell
+   ```bash
    rush build
    ```
 
 How to invoke your locally build `sparo` command:
 
-```shell
+```bash
 cd apps/sparo
 node lib/start.js
 ```