fix: match the branch-deploy context when using --context branch:foo (#7235)

* fix: match `branch-deploy` context when using `--context branch:foo`

The `--context` parameter can be passed to `dev`, `serve`, `functions:serve`, and
`deploy`.

As documented, its value can be a valid context (`all', 'production', 'deploy-preview',
'branch-deploy', 'dev`) or `branch:foo` where `foo` is the name of a branch.

In the former case, we match env vars with a matching `context`.

In the latter case, the intent is to match env vars with `context: "branch"` and
a `context_parameter` matching the branch name (`foo`).

All these behaviours are working as intended.

However, in addition to these, it's expected that using `--context branch:foo` implicitly
inherits the `branch-deploy` context as well (although a matching `branch` context value
should take precedence). This was not implemented.

You might think this is unnecessary: if you don't need the override, just use `--context
branch-deploy`. However, consider multiple environment variables, some of which have
branch-specific overrides, some of which do not. There is currently no mechanism available
to make this work as expected.

This commit fixes that, by simply adding the missing logic.

* fix(docs): improve inline help and docs for `--context`

* fix: use smart quotes in build --context docs docs

* fix: fix typo in deploy --context docs

Author: serhalp

docs/commands/build.md

@@ -17,7 +17,7 @@ netlify build
 
 **Flags**
 
-- `context` (*string*) - Specify a build context or branch (contexts: "production", "deploy-preview", "branch-deploy", "dev")
+- `context` (*string*) - Specify a deploy context for environment variables read during the build (”production”, ”deploy-preview”, ”branch-deploy”, ”dev”) or `branch:your-branch` where `your-branch` is the name of a branch (default: value of CONTEXT or ”production”)
 - `dry` (*boolean*) - Dry run: show instructions without running them
 - `filter` (*string*) - For monorepos, specify the name of the application to run the command in
 - `debug` (*boolean*) - Print debugging information
@@ -28,6 +28,8 @@ netlify build
 
 ```bash
 netlify build
+netlify build --context deploy-preview # Build with env var values from deploy-preview context
+netlify build --context branch:feat/make-it-pop # Build with env var values from the feat/make-it-pop branch context or branch-deploy context
 ```
 
 

docs/commands/deploy.md

@@ -87,7 +87,7 @@ netlify deploy
 - `alias` (*string*) - Specifies the alias for deployment, the string at the beginning of the deploy subdomain. Useful for creating predictable deployment URLs. Avoid setting an alias string to the same value as a deployed branch. `alias` doesn’t create a branch deploy and can’t be used in conjunction with the branch subdomain feature. Maximum 37 characters.
 - `branch` (*string*) - Serves the same functionality as --alias. Deprecated and will be removed in future versions
 - `build` (*boolean*) - Run build command before deploying
-- `context` (*string*) - Context to use when resolving build configuration
+- `context` (*string*) - Specify a deploy context for environment variables read during the build (”production”, ”deploy-preview”, ”branch-deploy”, ”dev”) or `branch:your-branch` where `your-branch` is the name of a branch (default: dev)
 - `dir` (*string*) - Specify a folder to deploy
 - `filter` (*string*) - For monorepos, specify the name of the application to run the command in
 - `functions` (*string*) - Specify a functions folder to deploy

docs/commands/dev.md

@@ -20,7 +20,7 @@ netlify dev
 **Flags**
 
 - `command` (*string*) - command to run
-- `context` (*string*) - Specify a deploy context or branch for environment variables (contexts: "production", "deploy-preview", "branch-deploy", "dev")
+- `context` (*string*) - Specify a deploy context for environment variables (”production”, ”deploy-preview”, ”branch-deploy”, ”dev”) or `branch:your-branch` where `your-branch` is the name of a branch (default: dev)
 - `country` (*string*) - Two-letter country code (https://ntl.fyi/country-codes) to use as mock geolocation (enables --geo=mock automatically)
 - `dir` (*string*) - dir with static files
 - `edge-inspect` (*string*) - enable the V8 Inspector Protocol for Edge Functions, with an optional address in the host:port format
@@ -49,7 +49,9 @@ netlify dev
 netlify dev
 netlify dev -d public
 netlify dev -c "hugo server -w" --target-port 1313
-netlify dev --context production
+netlify dev --context production # Use env var values from production context
+netlify dev --context deploy-preview # Use env var values from deploy-preview context
+netlify dev --context branch:feat/make-it-pop # Use env var values from the feat/make-it-pop branch context or branch-deploy context
 netlify dev --edge-inspect
 netlify dev --edge-inspect=127.0.0.1:9229
 netlify dev --edge-inspect-brk
@@ -74,7 +76,7 @@ netlify dev:exec
 
 **Flags**
 
-- `context` (*string*) - Specify a deploy context or branch for environment variables (contexts: "production", "deploy-preview", "branch-deploy", "dev")
+- `context` (*string*) - Specify a deploy context for environment variables (”production”, ”deploy-preview”, ”branch-deploy”, ”dev”) or `branch:your-branch` where `your-branch` is the name of a branch (default: dev)
 - `filter` (*string*) - For monorepos, specify the name of the application to run the command in
 - `debug` (*boolean*) - Print debugging information
 - `auth` (*string*) - Netlify auth token - can be used to run this command without logging in
@@ -83,6 +85,8 @@ netlify dev:exec
 
 ```bash
 netlify dev:exec npm run bootstrap
+netlify dev:exec --context deploy-preview npm run bootstrap # Run with env var values from deploy-preview context
+netlify dev:exec --context branch:feat/make-it-pop npm run bootstrap # Run with env var values from the feat/make-it-pop branch context or branch-deploy context
 ```
 
 ---

docs/commands/env.md

@@ -87,7 +87,7 @@ netlify env:get
 
 **Flags**
 
-- `context` (*string*) - Specify a deploy context or branch (contexts: "production", "deploy-preview", "branch-deploy", "dev")
+- `context` (*string*) - Specify a deploy context for environment variables (”production”, ”deploy-preview”, ”branch-deploy”, ”dev”) or `branch:your-branch` where `your-branch` is the name of a branch
 - `filter` (*string*) - For monorepos, specify the name of the application to run the command in
 - `json` (*boolean*) - Output environment variables as JSON
 - `debug` (*boolean*) - Print debugging information
@@ -99,7 +99,7 @@ netlify env:get
 ```bash
 netlify env:get MY_VAR # get value for MY_VAR in dev context
 netlify env:get MY_VAR --context production
-netlify env:get MY_VAR --context branch:staging
+netlify env:get MY_VAR --context branch:feat/make-it-pop # get value in the feat/make-it-pop branch context or branch-deploy context
 netlify env:get MY_VAR --scope functions
 ```
 
@@ -139,7 +139,7 @@ netlify env:list
 
 **Flags**
 
-- `context` (*string*) - Specify a deploy context or branch (contexts: "production", "deploy-preview", "branch-deploy", "dev")
+- `context` (*string*) - Specify a deploy context for environment variables (”production”, ”deploy-preview”, ”branch-deploy”, ”dev”) or `branch:your-branch` where `your-branch` is the name of a branch (default: all contexts)
 - `filter` (*string*) - For monorepos, specify the name of the application to run the command in
 - `json` (*boolean*) - Output environment variables as JSON
 - `scope` (*builds | functions | post-processing | runtime | any*) - Specify a scope
@@ -152,7 +152,7 @@ netlify env:list
 ```bash
 netlify env:list # list variables with values in the dev context and with any scope
 netlify env:list --context production
-netlify env:list --context branch:staging
+netlify env:list --context branch:feat/make-it-pop # list variables with values in the feat/make-it-pop branch context or branch-deploy context
 netlify env:list --scope functions
 netlify env:list --plain
 ```
@@ -175,7 +175,7 @@ netlify env:set
 
 **Flags**
 
-- `context` (*string*) - Specify a deploy context or branch (contexts: "production", "deploy-preview", "branch-deploy", "dev") (default: all contexts)
+- `context` (*string*) - Specify a deploy context for environment variables (”production”, ”deploy-preview”, ”branch-deploy”, ”dev”) or `branch:your-branch` where `your-branch` is the name of a branch (default: all contexts)
 - `filter` (*string*) - For monorepos, specify the name of the application to run the command in
 - `force` (*boolean*) - Bypasses prompts & Force the command to run.
 - `json` (*boolean*) - Output environment variables as JSON
@@ -189,7 +189,8 @@ netlify env:set
 ```bash
 netlify env:set VAR_NAME value # set in all contexts and scopes
 netlify env:set VAR_NAME value --context production
-netlify env:set VAR_NAME value --context production deploy-preview
+netlify env:set VAR_NAME value --context production deploy-preview # set in the production and deploy-preview contexts
+netlify env:set VAR_NAME value --context branch:feat/make-it-pop # set in the feat/make-it-pop branch context
 netlify env:set VAR_NAME value --context production --secret
 netlify env:set VAR_NAME value --scope builds
 netlify env:set VAR_NAME value --scope builds functions
@@ -213,7 +214,7 @@ netlify env:unset
 
 **Flags**
 
-- `context` (*string*) - Specify a deploy context or branch (contexts: "production", "deploy-preview", "branch-deploy", "dev") (default: all contexts)
+- `context` (*string*) - Specify a deploy context for environment variables (”production”, ”deploy-preview”, ”branch-deploy”, ”dev”) or `branch:your-branch` where `your-branch` is the name of a branch (default: all contexts)
 - `filter` (*string*) - For monorepos, specify the name of the application to run the command in
 - `force` (*boolean*) - Bypasses prompts & Force the command to run.
 - `json` (*boolean*) - Output environment variables as JSON
@@ -226,6 +227,7 @@ netlify env:unset
 netlify env:unset VAR_NAME # unset in all contexts
 netlify env:unset VAR_NAME --context production
 netlify env:unset VAR_NAME --context production deploy-preview
+netlify env:unset VAR_NAME --context branch:feat/make-it-pop # unset in the feat/make-it-pop branch context
 ```
 
 ---

docs/commands/serve.md

@@ -20,7 +20,7 @@ netlify serve
 
 **Flags**
 
-- `context` (*string*) - Specify a deploy context or branch for environment variables (contexts: "production", "deploy-preview", "branch-deploy", "dev")
+- `context` (*string*) - Specify a deploy context for environment variables (”production”, ”deploy-preview”, ”branch-deploy”, ”dev”) or `branch:your-branch` where `your-branch` is the name of a branch (default: dev)
 - `country` (*string*) - Two-letter country code (https://ntl.fyi/country-codes) to use as mock geolocation (enables --geo=mock automatically)
 - `dir` (*string*) - dir with static files
 - `filter` (*string*) - For monorepos, specify the name of the application to run the command in
@@ -37,6 +37,9 @@ netlify serve
 ```bash
 netlify serve
 BROWSER=none netlify serve # disable browser auto opening
+netlify serve --context production # Use env var values from production context
+netlify serve --context deploy-preview # Use env var values from deploy-preview context
+netlify serve --context branch:feat/make-it-pop # Use env var values from the feat/make-it-pop branch context or branch-deploy context
 ```
 
 

package-lock.json

@@ -173,6 +173,7 @@
     "@types/inquirer-autocomplete-prompt": "3.0.3",
     "@types/jsonwebtoken": "9.0.9",
     "@types/lodash": "4.17.16",
+    "@types/lodash.shuffle": "^4.2.9",
     "@types/multiparty": "4.2.1",
     "@types/node": "18.19.86",
     "@types/node-fetch": "2.6.12",
@@ -195,6 +196,7 @@
     "eslint-config-prettier": "10.1.2",
     "eslint-plugin-n": "17.17.0",
     "form-data": "4.0.2",
+    "lodash.shuffle": "^4.2.0",
     "memfs": "^4.17.0",
     "nock": "14.0.4",
     "npm-run-all2": "^7.0.2",

package.json

@@ -9,13 +9,17 @@ export const createBuildCommand = (program: BaseCommand) =>
     .description('Build on your local machine')
     .option(
       '--context <context>',
-      'Specify a build context or branch (contexts: "production", "deploy-preview", "branch-deploy", "dev")',
+      'Specify a deploy context for environment variables read during the build (”production”, ”deploy-preview”, ”branch-deploy”, ”dev”) or `branch:your-branch` where `your-branch` is the name of a branch (default: value of CONTEXT or ”production”)',
       normalizeContext,
       process.env.CONTEXT || 'production',
     )
     .option('--dry', 'Dry run: show instructions without running them', false)
     .option('-o, --offline', 'Disables any features that require network access')
-    .addExamples(['netlify build'])
+    .addExamples([
+      'netlify build',
+      'netlify build --context deploy-preview # Build with env var values from deploy-preview context',
+      'netlify build --context branch:feat/make-it-pop # Build with env var values from the feat/make-it-pop branch context or branch-deploy context',
+    ])
     .action(async (options, command) => {
       const { build } = await import('./build.js')
       await build(options, command)

src/commands/build/index.ts

@@ -110,7 +110,10 @@ Support for package.json's main field, and intrinsic index.js entrypoints are co
       ),
     )
     .option('--build', 'Run build command before deploying', false)
-    .option('--context <context>', 'Context to use when resolving build configuration')
+    .option(
+      '--context <context>',
+      'Specify a deploy context for environment variables read during the build (”production”, ”deploy-preview”, ”branch-deploy”, ”dev”) or `branch:your-branch` where `your-branch` is the name of a branch (default: dev)',
+    )
     .option(
       '--skip-functions-cache',
       'Ignore any functions created as part of a previous `build` or `deploy` commands, forcing them to be bundled again as part of the deployment',

src/commands/deploy/index.ts

@@ -9,15 +9,19 @@ export const createDevExecCommand = (program: BaseCommand) =>
     .argument('<...cmd>', `the command that should be executed`)
     .option(
       '--context <context>',
-      'Specify a deploy context or branch for environment variables (contexts: "production", "deploy-preview", "branch-deploy", "dev")',
+      'Specify a deploy context for environment variables (”production”, ”deploy-preview”, ”branch-deploy”, ”dev”) or `branch:your-branch` where `your-branch` is the name of a branch (default: dev)',
       normalizeContext,
       'dev',
     )
     .description(
       'Runs a command within the netlify dev environment. For example, with environment variables from any installed add-ons',
     )
     .allowExcessArguments(true)
-    .addExamples(['netlify dev:exec npm run bootstrap'])
+    .addExamples([
+      'netlify dev:exec npm run bootstrap',
+      'netlify dev:exec --context deploy-preview npm run bootstrap # Run with env var values from deploy-preview context',
+      'netlify dev:exec --context branch:feat/make-it-pop npm run bootstrap # Run with env var values from the feat/make-it-pop branch context or branch-deploy context',
+    ])
     .action(async (cmd: string, options: OptionValues, command: BaseCommand) => {
       const { devExec } = await import('./dev-exec.js')
       await devExec(cmd, options, command)