Bark
“Smart file header management and directory tree generation”
A fast Rust CLI that stamps standardized path headers onto every source file in a project and generates a directory tree — idempotently, in parallel, with atomic writes and timestamped backups so it never corrupts a file. Supports 74+ file types across four comment styles, a template system, watch mode, and a CI-ready check command.
Tech Stack
Technologies & tools used
Backend
6Rust
v2021 edition
Core language — a single static binary per platform, LTO-optimized release profile
clap
v4.5
Derive-based CLI parsing for all nine subcommands and their flags
rayon
v1.10
Data-parallel file processing — every tag/strip/check run fans out across all cores
ignore
v0.4
Gitignore-aware directory walking (the same crate ripgrep uses), extended with .barkignore support
notify
v6.1
OS file-system notification events powering watch mode's real-time tagging
tempfile
v3.10
Atomic writes — content goes to a tempfile in the target's directory, then a same-filesystem rename
Features & Highlights
Key capabilities and achievements
Idempotent header engine
CoreEach file is classified as current, stale, or missing a header, then rewritten deterministically — shebangs stay on line 0, CRLF line endings are preserved, and exactly one blank line follows the header. Running bark twice is always a no-op.
Atomic writes + timestamped backups
CoreBefore modifying a file, bark copies it to .barks/ with a timestamp; the new content is then written to a tempfile in the same directory and renamed into place, preserving permissions. bark restore reverts any change, bark clean prunes old backups.
74+ file types, four comment styles
CoreSlash (//), hash (#), CSS (/* */), and HTML (<!-- -->) styles cover everything from Rust and Go to Terraform, Svelte, and shaders — plus extensionless files like Dockerfile and Makefile. Custom extensions and filenames are one config line away.
Template-driven headers
CoreHeader text is a template with {{file}}, {{date}}, {{year}}, {{author}} (resolved from git config), {{project}}, {{filename}}, {{ext}}, and user-defined variables — overridable per extension or per run.
Directory tree generation
CoreEvery tag run (or bark tree standalone) writes a bark.txt tree of the project honoring the same ignore rules — a always-fresh structure snapshot for READMEs and onboarding.
Watch mode without feedback loops
bark watch tags files as they're saved, batching editor burst-saves in a debounce window and tracking its own writes in a recently-written set so it never re-triggers on itself.
CI and pre-commit ready
bark check exits 1 when any header is missing or stale; bark tag --staged processes only git-staged files — together they make a two-line pre-commit hook.
Parallel and project-aware
Files are processed across all cores with rayon; binary files (sniffed content, not extension), oversized files, and gitignored paths are skipped automatically; bark init --detect writes a config tailored to React/TypeScript/Go/Rust/Terraform/Docker projects.
System Architecture
A pipeline of small modules: walk, decide, write — safely
Bark is structured as a pipeline. The walker (built on the ignore crate) produces the set of files to consider, layering .gitignore, .barkignore, config exclude patterns, size limits, and content-based binary detection. The header engine is pure logic: given file content and a rendered template, it decides whether the header is current, stale, or missing, and computes the new content while preserving shebangs, CRLF endings, and trailing newlines. The processor fans that work out across cores with rayon and aggregates results in atomic counters. All mutation funnels through the backup manager, which owns the two safety primitives: timestamped backups and atomic tempfile-rename writes. Watch mode wraps the same processor behind a debounced notify event loop, and the template module renders {{variable}} placeholders from git config, the filesystem, and user-defined values.
Components
Walker
ServiceGitignore-aware file discovery with bark-specific layers on top.
- Honor .gitignore, the global git ignore, .git/info/exclude, and .barkignore
- Apply [exclude] glob patterns and the extension/filename skip lists
- Skip binary files by sniffing the first 8 KB of content, plus files over the size limit
- Exclude bark's own output file and backup directory from processing
Header engine
ServicePure content transformation — no I/O — which is what makes it exhaustively unit-testable.
- Classify each file: header current, stale, or missing
- Insert or replace the header at line 0, or line 1 after a shebang
- Preserve CRLF line endings and trailing newlines; normalize to exactly one blank line after the header
- Map 74+ extensions and known extensionless filenames to their comment style
Processor
ServiceThe parallel execution layer shared by tag, strip, check, staged mode, and watch mode.
- Fan file processing out across all cores with par_iter
- Aggregate tagged/updated/current/skipped/error counts in atomic counters
- Resolve template precedence: CLI override → per-extension override → default
- Resolve {{author}} from git config in a spawned thread with a 2-second timeout so a hung git can never hang bark
Backup manager
ServiceThe safety layer every write goes through — nothing else in the codebase touches file content on disk.
- Copy each file to .barks/<path>.<timestamp>.bak before modification, mirroring the source tree
- Write atomically: tempfile in the target's own directory, then a same-filesystem rename
- Capture and restore the original file permissions across the write
- Back restore (interactive or --latest) and clean --keep N
Watcher
ServiceReal-time tagging on file save, designed to be loop-proof and testable.
- Collect burst saves inside a configurable debounce window before processing
- Track bark's own writes in a recently-written set to prevent self-tagging loops
- Regenerate bark.txt after each processed batch
- Expose a stop flag so the infinite loop can be driven by integration tests
Challenges & Solutions
Problems solved and lessons learned
Recognizing a header written by any template
TechnicalIdempotency needs bark to recognize its own header on the next run — but the header text is user-configurable, so there is no fixed string to look for. Match too narrowly and changing the template strands old headers (bark would stack a second header on top). Match too broadly and bark might treat an unrelated leading comment as its own.
Solution
Chose a deliberately broad detection rule: any comment in the file's comment style on the first content line (after a shebang) is treated as the managed header and replaced. That makes template changes, path renames, and re-runs all converge to a single correct header.
Outcome
Idempotence holds under every template and rename scenario, verified by a run-twice integration test asserting byte-identical files.
Making thousands of file writes crash-safe
TechnicalA tool that rewrites every file in a repository has one unforgivable failure mode: a crash, full disk, or kill signal mid-write leaving a half-written source file. Naive fs::write truncates the file before writing — the exact window that destroys data.
Solution
Every write creates a tempfile in the target's own directory (guaranteeing the rename stays on one filesystem, which is what makes it atomic), writes and flushes the full content, copies the original file's permissions onto the tempfile, and only then renames it over the target. A timestamped backup is taken before any of that starts.
Outcome
At every instant, the file on disk is either the complete old version or the complete new version — never a mixture — and even a bad outcome is one bark restore away from undone.
Watch mode that doesn't tag its own writes forever
TechnicalWatch mode tags files when they change — but tagging a file changes it, which emits another change event, which would tag it again in an infinite loop. And an infinite event loop is also inherently hard to integration-test.
Solution
Before writing, the watcher records the path in a mutex-guarded recently-written set; when that path's own event arrives it is consumed and skipped (and removed from the set if the write failed). For testability, the loop polls an optional atomic stop flag every 100ms, so tests can run the real watcher, save files, and shut it down deterministically.
Outcome
Watch mode runs indefinitely without self-triggering, editor burst-saves collapse into one debounced batch, and the whole loop is covered by real integration tests instead of being an untested corner.
Key Learnings
What building a file-rewriting CLI teaches about safety and testability
Keep the dangerous part pure
TechnicalThe header engine takes strings in and returns strings out — zero I/O. Every edge case (shebangs, CRLF, blank-line collapsing, empty files) is a plain unit test.
Early sketches mixed file reading, decision logic, and writing in one function — every test needed a real file on disk.
analyze() and apply_tag() are pure functions over content; only the thin processor layer touches the filesystem.
Separate deciding from doing. The logic that could destroy data should be the easiest code in the project to test.
Subprocesses need timeouts, always
TechnicalBark shells out to git for the {{author}} variable and staged-file lists. A repository with a hung credential helper or slow filesystem would have made bark hang silently at startup.
Direct Command::output() calls that block indefinitely if git does.
Every git call runs in a spawned thread with an mpsc receive timeout (2s for author lookup, 5s for staged files) and a graceful fallback.
Any CLI that shells out inherits the worst-case behavior of every tool it calls — cap it.
Design infinite loops for their tests
ProcessThe watch loop originally ran forever with no way for a test to stop it — so it had no tests.
run() looped on blocking event receives; integration tests couldn't exercise watch mode at all.
run_until_stopped() takes an optional Arc<AtomicBool> and polls it between events; production passes None, tests flip the flag.
If a piece of code can't be shut down from the outside, it can't be tested from the outside — build the escape hatch in from day one.
Key Takeaways
- •Atomicity comes from the rename, and the rename is only atomic on one filesystem — put the tempfile next to the target, not in /tmp.
- •Idempotency is a spec decision before it's an implementation detail: define what 'already tagged' means precisely, then test the run-twice case.
- •Backups turn a scary tool into a boring one — every destructive default should have an undo.
- •Black-box tests of the compiled binary (assert_cmd) catch what unit tests can't: flag parsing, exit codes, and real filesystem behavior.
Roadmap
Known limitations and planned improvements
Planned
Smarter header detection
The deliberately broad first-line comment match can absorb a pre-existing ordinary comment (e.g. a copyright line). A marker-based or template-shape-aware detector would remove the tradeoff while keeping idempotence.
Publish to crates.io
Installation currently goes through the GitHub release binaries or cargo install --git; a crates.io release would enable plain cargo install bark.
Ideas & Backlog
Multi-line header blocks
LowHeaders are currently a single line; some teams want multi-line banners (license + path + author) managed with the same idempotence guarantees.
First-party editor integration
LowA VS Code extension wrapping bark watch would remove the need for a separate terminal process.
AI-readable content
Learn more →This content is available via the AI Content API as JSON or token-efficient Markdown. Feed it directly into LLM workflows.
/api/content/projects/barkRelated Content
Explore related articles, projects, and tools.