Breath

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

Note on features: this binary is built with Cargo features to target a VCS. The default feature is git. You must not enable both features at once (the build will fail): --features git OR --features hg.

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 (conditional on features)
  • Default build includes the git module
  • --features hg switches the entry to the hg module

Requirements

• Rust toolchain with edition 2024 support (Rust 1.82+ recommended)
• One of:
  • Git (for git feature)
  • Mercurial/hg (for hg feature)
• 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 (default: Git feature):

cargo install breath

Build explicitly for Git or Mercurial:

# Git (explicit)
cargo install breath --no-default-features --features git

# Mercurial
cargo install breath --no-default-features --features hg

From source (in this repo):

# Git (default)
cargo build --release

# Mercurial
cargo build --release --no-default-features --features hg

Usage

Interactive commit flow (Git default):

breath

Run the Mercurial build:

breath  # if you installed with --features hg
# or, from source without installing:
cargo run --no-default-features --features hg

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 (default/git): cargo build --release
• Build (hg): cargo build --release --no-default-features --features hg
• Run (default/git): cargo run
• Run (hg): cargo run --no-default-features --features hg
• Install locally: cargo install --path .

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, features (default = ["git"]) 
├── src
│   ├── main.rs          # feature-gated entry (git or 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 Git flow
├── 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.