Skip to content

docs: explain configuration before creating custom environments - #2459

Open
shabeeth2 wants to merge 1 commit into
pypa:masterfrom
shabeeth2:review/C05-2026-10-04
Open

shabeeth2 wants to merge 1 commit into
pypa:masterfrom
shabeeth2:review/C05-2026-10-04

Conversation

@shabeeth2

@shabeeth2 shabeeth2 commented Oct 4, 2026 •

Copy link
Copy Markdown

Summary

Clarify that hatch env create does not define environments; it only creates environments that are already defined in project configuration.

This updates the command docstring to explain the expected configuration locations:

  • pyproject.toml: [tool.hatch.envs.ENV_NAME]
  • hatch.toml: [envs.ENV_NAME]

The implicit default environment remains available without an explicit definition.

Why

The previous docstring was ambiguous and could be read as though hatch env create were responsible for creating or modifying environment configuration. In practice, the command reads existing configuration and creates the environment from it.

Related issue

Related: #1504

Validation

  • hatch run docs:build-check passed
  • Reviewed the CLI help text and rendered environment documentation
  • git diff --check passed

AI assistance: OpenAI Codex assisted with the edits, description and verification.

@shabeeth2
shabeeth2 marked this pull request as ready for review October 4, 2026 16:52
@shabeeth2 shabeeth2 changed the title docs: clarify configuration before environment creation docs: explain configuration before creating custom environments Oct 4, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant