# GitStatus
A fast, modern Rust tool that provides concise git repository status information. Perfect for shell prompts, scripts, and large repositories/monorepos.
## Features
- **Fast**: Pure Rust implementation using `gix` (Gitoxide)
- **Concise**: Shows branch, upstream, and change summary in minimal format
- **Modern**: Built with modern Rust patterns and best practices
- **Safe**: Proper error handling and memory safety
- **Configurable**: CLI options for different use cases
## Installation
### From Source
```bash
git clone https://github.com/stephenyu/gitstatus.git
cd gitstatus
cargo install --path .
```
### Using Cargo
```bash
cargo install gitstatus
```
## Usage
### Basic Usage
```bash
# In any git repository
gitstatus
# Output: main origin/main ✓
# With changes
gitstatus
# Output: main origin/main +2~1-1
```
### Command Line Options
```bash
# Show help
gitstatus --help
# Specify a different repository path
gitstatus --path /path/to/repo
# Show verbose error messages
gitstatus --verbose
```
## Output Format
The output consists of three parts separated by spaces:
1. **Current Branch**: Name of the current branch (or "HEAD" if detached)
2. **Upstream Branch**: Name of the upstream branch (if configured and different from current)
3. **Changes Summary**: Summary of repository changes
### Change Summary Symbols
- `✓` - Clean working directory
- `+N` - N added files
- `~N` - N modified files
- `-N` - N deleted files
- `rN` - N renamed files
- `tN` - N files with type changes
## Examples
```bash
# Clean repository on main branch tracking origin/main
$ gitstatus
main origin/main ✓
# Repository with changes
$ gitstatus
main origin/main +2~3-1
# Detached HEAD state
$ gitstatus
HEAD ✓
# Branch without upstream
$ gitstatus
feature-branch +1
```
## What's New in v0.3.0
This version represents a complete modernization of the codebase:
### 🚀 **Modern Rust Patterns**
- **Better Error Handling**: Uses `anyhow` for context-rich error messages
- **CLI Arguments**: Proper CLI parsing with `clap` derive macros
- **Type Safety**: Structured data types instead of string manipulation
- **Memory Safety**: No more potential panics from string indexing
### 🏗️ **Improved Architecture**
- **Separation of Concerns**: Clear separation between data collection, processing, and output
- **Pure `gix`**: Eliminated external `git` command calls in favor of `gix` (Gitoxide)
- **Structured Status**: Uses `gix::status` platform and `tree_index_status()` for precise, fast diffs
- **Extensible Design**: Easy to add new features and status indicators
### ⚡ **Performance Improvements**
- **Fast default**: Avoid scanning untracked files by default (equivalent to `git -uno`)
- **Parallel checks**: Uses `gix` parallel feature to check tracked-file modifications efficiently
- **Minimal I/O**: No process spawning; tracked-only checks for prompt use are extremely fast
### 🛡️ **Reliability**
- **Proper Error Propagation**: No more silent failures with `process::exit(1)`
- **Graceful Handling**: Better handling of edge cases (detached HEAD, no upstream, etc.)
- **Input Validation**: Validates repository paths and handles invalid UTF-8
### 🎯 **User Experience**
- **Better Symbols**: More intuitive change indicators (`~` for modified vs `+` for added)
- **Verbose Mode**: Optional detailed error messages for debugging
- **Flexible Paths**: Can check status of any repository, not just current directory
- **Help System**: Proper help and version information
## How it’s fast (with gix)
By default, `gitstatus` is optimized for shell prompts and large repos:
- It compares `HEAD^{tree}` to the index for staged changes using `Repository::tree_index_status()`.
- It compares the index to the working tree using `Repository::status(...).into_index_worktree_iter(...)` with untracked disabled unless requested.
- Untracked mode mapping:
- default / `-u no`: no untracked scan (no dirwalk)
- `-u normal`: collapsed untracked
- `-u all` or `--all`: full untracked listing
- Submodule checks and rename tracking are disabled by default for speed; they can be enabled later if needed.
## Development
```bash
# Build
cargo build
# Run tests
cargo test
# Run with development features
cargo run -- --verbose
# Check formatting and lints
cargo fmt --check
cargo clippy
```
## Requirements
- Rust 1.70+ (specified in Cargo.toml)
- Git repository to analyze
## License
GPL-3.0-only
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.