Skip to content

docs: add example for --workspace_status_command #28462

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
shivanshjais22 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: add example for --workspace_status_command #28462

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions site/en/docs/user-manual.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1209,6 +1209,32 @@ the value may span multiple lines. Keys must not be duplicated.
Bazel partitions the keys into two buckets: "stable" and "volatile". (The names "stable" and
"volatile" are a bit counter-intuitive, so don't think much about them.)

#### Example

The following example shows how `--workspace_status_command` can be used
to generate build metadata and consume it during a build.

Create a workspace status script:

```sh
#!/usr/bin/env sh
echo "BUILD_USER $(whoami)"
echo "BUILD_TIMESTAMP $(date +%s)"

Make the script executable:
chmod +x status.sh


bazel build //:gen_metadata --workspace_status_command=./status.sh

genrule(
name = "gen_metadata",
outs = ["metadata.txt"],
cmd = "cat bazel-out/volatile-status.txt > $@",
stamp = 1,
)


Comment on lines +1212 to +1237
Copy link

@gemini-code-assist gemini-code-assist bot Jan 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

critical

The example for --workspace_status_command has several issues that make it confusing and will cause rendering problems:

  1. Markdown Syntax Error: There is a missing closing ```` for the code block, which will cause the rest of the document to be rendered as code.
  2. Incorrect Content in Code Block: The sh code block contains user instructions (Make the script executable:) and a genrule definition (which is Python/Starlark syntax), neither of which are part of the shell script itself.
  3. Confusing Structure: The example mixes file content, shell commands, and build rule definitions without clear separation or explanation of how they relate. For instance, the bazel build command appears before the genrule it's supposed to build.

I've suggested a rewrite that structures the example as a clear, step-by-step guide and fixes the formatting issues.

#### Example

The following example shows how `--workspace_status_command` can be used
to generate build metadata and consume it during a build.

First, create a workspace status script named `status.sh`:

```sh
#!/usr/bin/env sh
echo "BUILD_USER $(whoami)"
echo "BUILD_TIMESTAMP $(date +%s)"

Next, make the script executable:

chmod +x status.sh

Then, create a BUILD file with a genrule that consumes the status information. The stamp = 1 attribute is required for the rule to see the status files.

genrule(
    name = "gen_metadata",
    outs = ["metadata.txt"],
    cmd = "cat bazel-out/volatile-status.txt > $@",
    stamp = 1,
)

Finally, run the build, pointing to your script with the --workspace_status_command flag:

bazel build //:gen_metadata --workspace_status_command=./status.sh

Bazel then writes the key-value pairs into two files:

* `bazel-out/stable-status.txt`
Expand Down