README
¶
tally
tally is a production-grade Dockerfile/Containerfile linter + formatter that keeps build files clean, modern, and consistent.
It uses BuildKit's official parser and checks (the same foundation behind docker buildx) plus a safe auto-fix engine. It runs fast,
doesn't require Docker Desktop or a daemon, and fits neatly into CI.
# Lint everything in the repo (recursive)
tally lint .
# Apply all safe fixes automatically
tally lint --fix Dockerfile
Why tally
Modern Dockerfiles deserve modern tooling. tally is opinionated in the right places:
- BuildKit-native: understands modern syntax like heredocs,
RUN --mount=...,COPY --link, andADD --checksum=.... - Fixes, not just findings:
--fixapplies safe, mechanical rewrites;--fix-unsafeunlocks opt-in risky fixes (including AI). - Modernizes on purpose: converts eligible
RUN/COPYinstructions to heredocs, prefers BuildKitADDsources for archives and git repos, and more. - Broad rule coverage: combines Docker's official BuildKit checks, embedded ShellCheck for shell snippets, Hadolint-compatible rules, and tally-specific rules.
- PowerShell-aware: parses full PowerShell syntax for semantic tokens and rule analysis, so PowerShell
RUNinstructions are treated as real code instead of opaque strings. - Windows-container aware: detects Windows container OS, understands Windows paths and default shells, and recognizes
cmd.exeand PowerShell-specific build patterns. - Registry-aware without Docker: uses a Podman-compatible registry client for image metadata checks (no daemon required).
- Editor + CI friendly: VS Code extension (
wharflab.tally, powered bytally lsp) and outputs for JSON, SARIF, and GitHub Actions annotations. - Easy to install anywhere: Homebrew, WinGet, Go, npm, pip, and RubyGems.
- Written in Go: single fast binary, built on production-grade libraries.
Quality bar: 92% code coverage on Codecov and 2,900+ Go tests executed in CI.
Documentation
For installation, usage, configuration, rules reference, and more, visit the full documentation at tally.wharflab.com.
Contributing
See CLAUDE.md for development guidelines.
License
GPL-3.0-only. See LICENSE for the full license text.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
internal
|
|
|
async
Package async provides a concurrency-limited runtime for executing potentially slow checks (registry access, network, filesystem) in a controlled, cancellable way.
|
Package async provides a concurrency-limited runtime for executing potentially slow checks (registry access, network, filesystem) in a controlled, cancellable way. |
|
config
Package config provides configuration loading and discovery for tally.
|
Package config provides configuration loading and discovery for tally. |
|
context
Package context provides build context awareness for Dockerfile linting.
|
Package context provides build context awareness for Dockerfile linting. |
|
directive
Package directive provides inline suppression directives for linting.
|
Package directive provides inline suppression directives for linting. |
|
discovery
Package discovery provides Dockerfile discovery with glob pattern support.
|
Package discovery provides Dockerfile discovery with glob pattern support. |
|
facts
Package facts provides a per-file derived-analysis layer for Dockerfiles.
|
Package facts provides a per-file derived-analysis layer for Dockerfiles. |
|
fileval
Package fileval provides pre-parse file validation checks for tally.
|
Package fileval provides pre-parse file validation checks for tally. |
|
fix
Package fix provides auto-fix infrastructure for tally.
|
Package fix provides auto-fix infrastructure for tally. |
|
heredoc
Package heredoc provides utilities for formatting heredoc RUN instructions.
|
Package heredoc provides utilities for formatting heredoc RUN instructions. |
|
highlight/tsutil
Package tsutil provides shared tree-sitter-to-core.Token helpers used by dialect-specific tokenizers (powershell, batch).
|
Package tsutil provides shared tree-sitter-to-core.Token helpers used by dialect-specific tokenizers (powershell, batch). |
|
invocation
Package invocation models planned Dockerfile build invocations produced by Dockerfile-oriented entrypoints and build orchestrators such as Bake and Compose.
|
Package invocation models planned Dockerfile build invocations produced by Dockerfile-oriented entrypoints and build orchestrators such as Bake and Compose. |
|
linter
Package linter provides the shared lint pipeline used by both the CLI and the LSP server.
|
Package linter provides the shared lint pipeline used by both the CLI and the LSP server. |
|
lsp/protocol
Package protocol contains generated LSP protocol types.
|
Package protocol contains generated LSP protocol types. |
|
lspserver
Package lspserver implements a Language Server Protocol server for tally.
|
Package lspserver implements a Language Server Protocol server for tally. |
|
processor
Package processor provides a composable violation processing pipeline.
|
Package processor provides a composable violation processing pipeline. |
|
registry
Package registry provides OCI registry integration for resolving base image configuration (env, platform, digest) via containers/image.
|
Package registry provides OCI registry integration for resolving base image configuration (env, platform, digest) via containers/image. |
|
registry/testutil
Package testutil provides a deterministic mock OCI registry for testing async checks that resolve image configs from registries.
|
Package testutil provides a deterministic mock OCI registry for testing async checks that resolve image configs from registries. |
|
reporter
Package reporter provides output formatters for lint results.
|
Package reporter provides output formatters for lint results. |
|
rules
Package rules provides the core rule system for the Dockerfile linter.
|
Package rules provides the core rule system for the Dockerfile linter. |
|
rules/all
Package all imports all rule packages to register them.
|
Package all imports all rule packages to register them. |
|
rules/asyncutil
Package asyncutil provides shared helpers for async rule implementations.
|
Package asyncutil provides shared helpers for async rule implementations. |
|
rules/buildkit
Package buildkit provides metadata for BuildKit's built-in linter rules.
|
Package buildkit provides metadata for BuildKit's built-in linter rules. |
|
rules/buildkit/fixes
Package fixes provides auto-fix enrichment for BuildKit linter rules.
|
Package fixes provides auto-fix enrichment for BuildKit linter rules. |
|
rules/configutil
Package configutil provides utilities for rule configuration resolution.
|
Package configutil provides utilities for rule configuration resolution. |
|
rules/hadolint
Package hadolint implements hadolint-compatible linting rules for Dockerfiles.
|
Package hadolint implements hadolint-compatible linting rules for Dockerfiles. |
|
rules/tally
Package tally implements tally-specific linting rules for Dockerfiles.
|
Package tally implements tally-specific linting rules for Dockerfiles. |
|
runmount
Package runmount provides utilities for working with RUN --mount options.
|
Package runmount provides utilities for working with RUN --mount options. |
|
semantic
Package semantic provides a semantic model for Dockerfiles that enables cross-instruction analysis such as stage resolution, variable scoping, and COPY --from validation.
|
Package semantic provides a semantic model for Dockerfiles that enables cross-instruction analysis such as stage resolution, variable scoping, and COPY --from validation. |
|
shell
Package shell provides shell script parsing utilities for Dockerfile linting.
|
Package shell provides shell script parsing utilities for Dockerfile linting. |
|
sourcemap
Package sourcemap provides utilities for working with source code locations, snippet extraction, and line-based operations.
|
Package sourcemap provides utilities for working with source code locations, snippet extraction, and line-based operations. |
|
syntax
Package syntax provides fail-fast AST-level correctness checks that run before the full lint pipeline.
|
Package syntax provides fail-fast AST-level correctness checks that run before the full lint pipeline. |
|
testutil
Package testutil provides test helpers for the Dockerfile linter.
|
Package testutil provides test helpers for the Dockerfile linter. |
Click to show internal directories.
Click to hide internal directories.