Breath

A fast, interactive CLI that streamlines committing code to Git or Mercurial repositories. It can also run language-aware checks before you commit (format, lint, tests, security, deps) and stores logs per language under a .breathes directory.

VCS detection: Breath auto-detects the repository type at runtime by checking for .git or .hg. No Cargo features are required to switch between Git and Mercurial.

Overview

Breath helps you:

• review the current diff and status;
• compose a guided commit message (templates with type, scope, summary);
• optionally push to remotes;
• run pre-commit hooks for common ecosystems when their config files are detected (Rust, Node.js, PHP, Go, Java, .NET/C#, CMake, etc.).

Under the hood it uses:

• Rust + Cargo as the build system;
• crossterm and inquire for the TUI/interactive prompts;
• simple process spawning to run the underlying tools for each language.

Stack and entry points

• Language: Rust (edition 2024)
• Package manager/build tool: Cargo
• Binary crate name: breath
• Entry point: src/main.rs
• VCS: auto-detected at runtime by checking for .git or .hg
• Subcommands: config, health, commit, push, pull, status, log, diff

Requirements

• Rust toolchain with edition 2024 support (Rust 1.82+ recommended)
• One of (depending on your repository):
  • Git (if using a Git repo)
  • Mercurial/hg (if using a Mercurial repo)
• Optional tools used by hooks (only needed if the corresponding project files exist):
  • Rust: rustfmt, clippy (rustup components), cargo-audit, cargo-outdated
  • Node.js: npm
  • PHP: composer
  • Go: go toolchain
  • Java: Maven (mvn)
  • .NET/C#: dotnet
  • CMake: cmake and make

If a language’s tool is not installed but its marker file exists (e.g., Cargo.toml), the related hook will fail. Install the tool or remove/ignore the marker.

Installation

From crates.io:

cargo install breath

From source (in this repo):

cargo build --release

Usage

Breath works the same in Git and Mercurial repositories. It auto-detects the VCS.

• Interactive commit flow:

breath commit
# or simply `breath` to run the default interactive flow (commit in detected VCS)

• Health checks (run language-aware hooks if their marker files exist):

breath health

• Configure your Git or Mercurial setup:

breath config git  # prompts for user.name, user.email, core.editor
breath config hg   # prints instructions to edit hg config

• Convenience passthroughs to the underlying VCS:

breath status
breath log
breath diff
breath push
breath pull

Example pre-commit hook:

#!/bin/sh
# .git/hooks/pre-commit (make sure it is executable)

breath && exit 0 || exit 1

Hooks and logs

Breath runs language-specific hooks based on the presence of well-known files in your repository:

• Rust: Cargo.toml → runs cargo fmt --check, clippy, test --no-fail-fast, audit, outdated
• Node.js: package.json → runs npm outdated, npm run test
• PHP: composer.json → runs composer outdated, composer security-check, php-cs-fixer (dry run), composer run test
• Go: go.mod → runs go fmt -x, go vet ./..., go test ./..., go mod tidy, go build
• Java: build.gradle or Maven project (see hooks.rs) → runs mvn clean compile, test, spotbugs, dependency updates
• C#: *.csproj → dotnet format --verify-no-changes, build, test, analyze, restore
• CMake: CMakeLists.txt → cmake build . && make . && make test

Outputs are stored under .breathes//{stdout,stderr}/.log. On failure, Breath prints the captured logs for quick diagnosis.

Scripts and common commands

• Build: cargo build --release
• Run: cargo run
• Install locally from source: cargo install --path .
• Show help: breath --help

Environment variables

• None required at this time.
• TODO: Document any future env vars to control timeouts, spinner behavior, or disabling certain hooks.

Tests

• There are currently no automated tests in this repository.
• To run tests when they are added: cargo test
• TODO: Add unit/integration tests for the interactive flow and hook runner.

Project structure

.
├── Cargo.toml           # crate metadata (name, version, license, deps)
├── src
│   ├── main.rs          # CLI entry point and subcommands; auto-detects Git/Hg
│   ├── git.rs           # Git workflow: diff, commit, optional push
│   ├── hg.rs            # Mercurial workflow: diff, commit, optional push
│   ├── utils.rs         # hooks runner, spinner UI, COMMIT_MESSAGE template
│   ├── hooks.rs         # per-language hook definitions
│   └── commit.rs        # commit type catalogue for the interactive menu
├── README.md
└── target/              # build artifacts (ignored)

License

AGPL-3.0. See the license badge above and Cargo.toml.

Acknowledgements

Created by hackia. Contributions and feedback are welcome.