tiktok-sparo/apps/website/docs/pages/guide/getting_started.md

title
Getting Started

🚧 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.

Everyday workflow

Step 1: Upgrade Git

Many Git optimizations are relatively new and not available in older versions of the software. For macOS, we recommend to use brew install git. For other operating systems, see the Git documentation for instructions.

Step 2: Clone your Rush monorepo

Clone your RushJS monorepo:

sparo clone https://github.com/my-company/my-monorepo.git

👉 For a real world demo, try this repo: https://github.com/Azure/azure-sdk-for-js.git

💡 Support for PNPM and Yarn workspaces is planned but not implemented yet. Contributions welcome!

Behind the scenes:

• Only the default branch (usually main) is fetched.

• Git blobless partial clone is enabled to postpone downloading file contents.

• Git sparse checkout is used to clone only the "skeleton" folders, which includes all workspace package.json files, but excludes the source code subfolders.

• Sparse checkout is configured for the more efficient "cone mode".

• To understand exactly what actions and Git operations are being performed, invoke sparo --debug clone instead of sparo clone.

Step 3: Create a sparse profile

Define a Sparo profile describing the subset of repository folders for Git sparse checkout. Here is a basic example:

common/sparo-profiles/my-team.json

{
  "selections": [
    {
      "selector": "--to",
      "argument": "my-rush-project"
    }
  ]
}

The --to project selector instructs Sparo to checkout all dependencies in the workspace that are required to build my-rush-project.

👉 If you're demoing azure-sdk-for-js, replace my-rush-project with @azure/arm-commerce.

Step 4: Check out your Sparo profile

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

sparo checkout --profile my-team

Behind the scenes:

• Sparo automatically generates the $GIT_DIR/info/sparse-checkout configuration automatically based on your profile selections. To avoid conflicts, while using Sparo do not edit this file directly or rewrite it using other tools such as git sparse-checkout.

• 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:

  sparo checkout --profile p1
  sparo checkout --add-profile p2
  

Step 5: Use the mirrored subcommands

For everyday work, consider choosing mirrored subcommands 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:

sparo pull

sparo commit -m "Example command"