diff --git a/docs/repo-docs/reference/meta.json b/docs/repo-docs/reference/meta.json index c3d1aec2e1c67..bc3b9f0b1fae6 100644 --- a/docs/repo-docs/reference/meta.json +++ b/docs/repo-docs/reference/meta.json @@ -6,7 +6,7 @@ "package-configurations", "system-environment-variables", "globs", - "options-one-pager", + "options-overview", "---Commands---", "run", "watch", diff --git a/docs/repo-docs/reference/options-one-pager.mdx b/docs/repo-docs/reference/options-one-pager.mdx index 8c3eb3325d14a..c066d6846e641 100644 --- a/docs/repo-docs/reference/options-one-pager.mdx +++ b/docs/repo-docs/reference/options-one-pager.mdx @@ -1,5 +1,5 @@ --- -title: Options one-pager +title: Options overview description: Flags, configurations, and System Environment Variables for Turborepo --- diff --git a/docs/repo-docs/reference/options-overview.mdx b/docs/repo-docs/reference/options-overview.mdx new file mode 100644 index 0000000000000..8c3eb3325d14a --- /dev/null +++ b/docs/repo-docs/reference/options-overview.mdx @@ -0,0 +1,118 @@ +--- +title: Options one-pager +description: Flags, configurations, and System Environment Variables for Turborepo +--- + +There are three ways to manage the behavior of a `turbo` invocation: + +- [Configuration in `turbo.json`](/repo/docs/reference/configuration) +- [System Environment Variables](/repo/docs/reference/system-environment-variables) +- [Flags passed to the CLI invocation](/repo/docs/reference/run) + +The three strategies listed above are in order of precedence. Where a flag value is provided, for the same System Environment Variable or `turbo.json` configuration, the value for the flag will be used. Because of this, we recommend using: + +- `turbo.json` configuration for defaults +- System Environment Variables for per-environment overrides +- Flags for per-invocation overrides + +## Options table + +### Caching + +
+ +| Behavior | Flags | Environment Variables | turbo.json | +| --------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | +| Force tasks to run | [`--force`](/repo/docs/reference/run#--force) | [`TURBO_FORCE`](/repo/docs/reference/system-environment-variables#turbo_force) | [`cache`](/repo/docs/reference/configuration#cache) | +| Remote Cache timeout | [`--remote-cache-timeout`](/repo/docs/reference/configuration#timeout) | [`TURBO_REMOTE_CACHE_TIMEOUT`](/repo/docs/reference/system-environment-variables#turbo_remote_cache_timeout) | [`remoteCache.timeout`](/repo/docs/reference/configuration#timeout) | +| Remote Cache upload timeout | - | [`TURBO_REMOTE_CACHE_UPLOAD_TIMEOUT`](/repo/docs/reference/system-environment-variables#turbo_remote_cache_upload_timeout) | [`remoteCache.uploadTimeout`](/repo/docs/reference/configuration#uploadtimeout) | +| Cache signature key | - | [`TURBO_REMOTE_CACHE_SIGNATURE_KEY`](/repo/docs/reference/system-environment-variables#turbo_remote_cache_signature_key) | [`signature`](/repo/docs/reference/configuration#signature) | +| Preflight request | [`--preflight`](/repo/docs/reference/run#--preflight) | [`TURBO_PREFLIGHT`](/repo/docs/reference/system-environment-variables#turbo_preflight) | [`remoteCache.preflight`](/repo/docs/reference/configuration#preflight) | +| Remote Cache base URL | - | [`TURBO_API`](/repo/docs/reference/system-environment-variables#turbo_api) | [`remoteCache.apiUrl`](/repo/docs/reference/configuration#remote-caching) | +| Cache sources | [`--cache`](/repo/docs/reference/run#--cache-options) | [`TURBO_CACHE`](/repo/docs/reference/system-environment-variables#turbo_cache) | - | +| Local cache directory | [`--cache-dir`](/repo/docs/reference/run#--cache-dir-path) | [`TURBO_CACHE_DIR`](/repo/docs/reference/system-environment-variables#turbo_cache_dir) | [`cacheDir`](/repo/docs/reference/configuration#cachedir) | + +
+ +### Messages + +
+ +| Behavior | Flags | Environment Variables | turbo.json | +| ------------------------------ | ----- | ------------------------------------------------------------------------------------------------------------------------ | ---------- | +| Disable version print | - | [`TURBO_PRINT_VERSION_DISABLED`](/repo/docs/reference/system-environment-variables#turbo_print_version_disabled) | - | +| Disable telemetry message | - | [`TURBO_TELEMETRY_MESSAGE_DISABLED`](/repo/docs/reference/system-environment-variables#turbo_telemetry_message_disabled) | - | +| Disable global `turbo` warning | - | [`TURBO_GLOBAL_WARNING_DISABLED`](/repo/docs/reference/system-environment-variables#turbo_global_warning_disabled) | - | +| No update notifier | - | [`TURBO_NO_UPDATE_NOTIFIER`](/repo/docs/reference/system-environment-variables#turbo_no_update_notifier) | - | + +
+ +### Task running and logs + +
+ +| Behavior | Flags | Environment Variables | turbo.json | +| --------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| Terminal UI | [`--ui`](/repo/docs/reference/run#--ui) | [`TURBO_UI`](/repo/docs/reference/system-environment-variables#turbo_ui) | [`ui`](/repo/docs/reference/configuration#ui) | +| Run affected tasks | [`--affected`](/repo/docs/reference/run#--affected) | - | - | +| Disable package manager check | [`--dangerously-disable-package-manager-check`](/repo/docs/reference/run#--dangerously-disable-package-manager-check) | [`TURBO_DANGEROUSLY_DISABLE_PACKAGE_MANAGER_CHECK`](/repo/docs/reference/system-environment-variables#turbo_dangerously_disable_package_manager_check) | [`dangerouslyDisablePackageManagerCheck`](/repo/docs/reference/configuration#dangerouslydisablepackagemanagercheck) | +| Affected base ref | - | [`TURBO_SCM_BASE`](/repo/docs/reference/system-environment-variables#turbo_scm_base) | - | +| Affected head ref | - | [`TURBO_SCM_HEAD`](/repo/docs/reference/system-environment-variables#turbo_scm_head) | - | +| Only run directly specified tasks | [`--only`](/repo/docs/reference/run#--only) | - | - | +| Task concurrency | [`--concurrency`](/repo/docs/reference/run#--concurrency-number--percentage) | - | - | +| Task log order | [`--log-order`](/repo/docs/reference/run#--log-order-option) | [`TURBO_LOG_ORDER`](/repo/docs/reference/system-environment-variables#turbo_log_order) | - | +| Current working directory | [`--cwd`](/repo/docs/reference/run#--cwd-path) | - | - | +| Streamed logs prefix | [`--log-prefix`](/repo/docs/reference/run#--log-prefix-option) | - | - | +| Task logs output level | [`--output-logs-option`](/repo/docs/reference/run#--output-logs-option) | - | [`outputLogs`](/repo/docs/reference/configuration#outputlogs) | +| Global inputs | [`--global-deps`](/repo/docs/reference/run#--global-deps-file-glob) | - | [`globalDependencies`](/repo/docs/reference/configuration#globaldependencies) | + +
+ +### Environment variables + +
+ +| Behavior | Flags | Environment Variables | turbo.json | +| ----------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | +| Environment variable mode | [`--env-mode`](/repo/docs/reference/run#--env-mode-option) | - | [`envMode`](/repo/docs/reference/configuration#envmode) | +| Vendor environment variables | - | [`TURBO_CI_VENDOR_ENV_KEY`](/repo/docs/reference/system-environment-variables#turbo_ci_vendor_env_key) | - | +| Framework variable exceptions | [`--framework-inference`](/repo/docs/reference/run#--framework-inference) | - | - | + +
+ +### Debugging outputs + +
+ +| Behavior | Flags | Environment Variables | turbo.json | +| ------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ---------- | +| Run Summaries | [`--summarize`](/repo/docs/reference/run#--summarize) | [`TURBO_RUN_SUMMARY`](/repo/docs/reference/system-environment-variables#turbo_run_summary) | - | +| Graph visualization | [`--graph`](/repo/docs/reference/run#--graph-file-type) | - | - | +| Dry run | [`--dry`](/repo/docs/reference/run#--dry----dry-run) | - | - | + +
+ +### Authentication + +
+ +| Behavior | Flags | Environment Variables | turbo.json | +| --------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------- | +| Login URL | - | [`TURBO_LOGIN`](/repo/docs/reference/system-environment-variables#turbo_login) | [`remoteCache.loginUrl`](/repo/docs/reference/configuration#loginurl) | +| Team name (for multi-team Remote Cache) | [`--team`](/repo/docs/reference/run#--team) | [`TURBO_TEAM`](/repo/docs/reference/system-environment-variables#turbo_team) | - | +| Team ID (for multi-team Remote Cache) | - | [`TURBO_TEAMID`](/repo/docs/reference/system-environment-variables#turbo_teamid) | - | +| Authentication token | [`--token`](/repo/docs/reference/run#--token) | [`TURBO_TOKEN`](/repo/docs/reference/system-environment-variables#turbo_token) | - | + +
+ +### Other + +
+ +| Behavior | Flags | Environment Variables | turbo.json | +| ---------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | +| Binary path | - | [`TURBO_BINARY_PATH`](/repo/docs/reference/system-environment-variables#turbo_binary_path) | - | +| Download local `turbo` | - | [`TURBO_DOWNLOAD_LOCAL_ENABLED`](/repo/docs/reference/system-environment-variables#turbo_download_local_enabled) | - | +| Daemon | [`--daemon` / `--no-daemon`](/repo/docs/reference/run#--daemon-and---no-daemon) | - | [`daemon`](/repo/docs/reference/configuration#daemon) | + +