Command Cheatsheet

This page is a quick command reference.

It does not explain every concept in detail.

For explanations, use the main learning path and quickstarts.

Project setup

Create a new project:

mkdir example-python-project
cd example-python-project
uv init --bare --name example-python-project --python 3.12
uv python pin 3.12

Create a basic src/ layout:

mkdir -p src/example_project tests
touch src/example_project/__init__.py
touch src/example_project/calculator.py
touch tests/test_calculator.py

Windows PowerShell:

New-Item -ItemType Directory -Force src/example_project
New-Item -ItemType Directory -Force tests
New-Item -ItemType File -Force src/example_project/__init__.py
New-Item -ItemType File -Force src/example_project/calculator.py
New-Item -ItemType File -Force tests/test_calculator.py

Dependencies

Add a runtime dependency:

uv add package-name

Example:

uv add rich

Add a development dependency:

uv add --group dev package-name

Examples:

uv add --group dev pytest
uv add --group dev ruff
uv add --group dev mypy
uv add --group dev pytest-cov
uv add --group dev pre-commit
uv add --group dev rumdl
uv add --group dev mkdocs

Sync the local environment:

uv sync

Lock dependencies explicitly:

uv lock

Running tools

Run tests:

uv run pytest

Run tests with coverage:

uv run pytest --cov=text_toolkit --cov-report=term-missing

Run type checking:

uv run mypy

Run Ruff linting:

uv run ruff check .

Check formatting:

uv run ruff format --check .

Format files:

uv run ruff format .

Lint Markdown files:

uv run rumdl check .

Preview the documentation site:

uv run mkdocs serve

Build the documentation site strictly:

uv run mkdocs build --strict

Install pre-commit hooks in the current clone:

uv run pre-commit install

Run every configured hook manually:

uv run pre-commit run --all-files

Remove the installed hook from the current clone:

uv run pre-commit uninstall

Run all local checks:

uv run ruff check .
uv run ruff format --check .
uv run rumdl check .
uv run mkdocs build --strict
uv run pytest --cov=text_toolkit --cov-report=term-missing
uv run mypy
uv build --no-sources

Build distributions

Build a wheel and source distribution:

uv build --no-sources

Generated files appear in dist/ and should stay uncommitted.

Fix formatting and recheck

If formatting fails:

uv run ruff format .
uv run ruff check .
uv run ruff format --check .
uv run rumdl check .
uv run mkdocs build --strict
uv run pytest --cov=text_toolkit --cov-report=term-missing
uv run mypy
uv build --no-sources

Clone an existing project

git clone https://github.com/your-username/your-project.git
cd your-project
uv sync

Then run:

uv run ruff check .
uv run ruff format --check .
uv run rumdl check .
uv run mkdocs build --strict
uv run pytest --cov=text_toolkit --cov-report=term-missing
uv run mypy

Git workflow

Update main:

git switch main
git pull

Create a branch:

git switch -c docs/example-change

Check changed files:

git status

Stage a file:

git add path/to/file.md

Commit:

git commit -m "docs: describe example change"

Push the branch:

git push -u origin docs/example-change

After the pull request is merged:

git switch main
git pull
git branch -d docs/example-change

Useful commit message examples

Documentation:

docs: add project glossary
docs: explain pytest
docs: update README quickstarts

Project configuration:

chore: initialize uv project
chore: configure ruff
chore: add editorconfig

Tests:

test: add text statistics tests

CI:

ci: add GitHub Actions workflow

Feature code:

feat: add text toolkit package

GitHub Actions CI

Minimal CI workflow commands:

uv python install
uv sync --locked --group dev
uv run ruff check .
uv run ruff format --check .
uv run rumdl check .
uv run mkdocs build --strict
uv run pytest --cov=text_toolkit --cov-report=term-missing
uv run mypy
uv build --no-sources

CI should use:

uv sync --locked --group dev

Local development usually uses:

uv sync

Files to commit

Usually commit:

README.md
CONTRIBUTING.md
LICENSE
pyproject.toml
uv.lock
.python-version
.github/
docs/
mkdocs.yml
src/
tests/

Do not commit:

.venv/
__pycache__/
.pytest_cache/
.ruff_cache/
.mypy_cache/
.rumdl_cache/
.coverage
htmlcov/
site/

Quick local checklist

Before opening a pull request with code changes:

git status
uv sync
uv run ruff check .
uv run ruff format --check .
uv run rumdl check .
uv run mkdocs build --strict
uv run pytest --cov=text_toolkit --cov-report=term-missing
uv run mypy

Before merging:

CI is green
PR title is clear
PR description explains what changed and why
Diff has been reviewed
No unrelated files are included