Skip to main content
This guide will walk you through your first scan with Dirty and help you understand the output.

​
Basic usage

1

Scan a directory

To scan a directory for git repositories, run Dirty with a path:
dirty ~/code
By default, Dirty searches up to 3 levels deep for git repositories.
2

Review the results

Dirty will display a list of all repositories found, with visual indicators for their status:
 * apps/dashboard
   apps/storefront
 * libs/ui-kit [local]
   libs/common
 * services/auth
   services/payments
   tools/cli [local]
 * tools/scripts [local]

8 repos, 4 dirty, 3 local-only
The scan runs in parallel using all available CPU cores, making it extremely fast even with hundreds of repositories.
3

Understand the output

Each line represents one git repository, with optional markers:
  • * (red) — Repository has uncommitted or untracked changes
  • [local] (yellow) — Repository has no remote configured
  • No marker — Repository is clean and has a remote
The summary line shows:
  • Total number of repositories found
  • Number of repos with uncommitted changes
  • Number of repos without remotes

​
Common use cases

​
Scan with custom depth

Control how deep Dirty searches for repositories: 
# Only scan immediate subdirectories
dirty -L 1 ~/code

# Search up to 5 levels deep
dirty -L 5 ~/projects

​
Show only dirty repos

Filter to see only repositories with uncommitted changes: 
dirty -d ~/code

​
Show only local-only repos

Find repositories that don’t have a remote configured: 
dirty -l ~/code

​
Check for unpushed commits

See which repositories have commits ahead of their upstream branch: 
dirty -u ~/code
This adds a [↑n] indicator showing how many commits are ahead: 
 * apps/dashboard [↑3]
   apps/storefront
The --include-unpushed flag is slower because it needs to resolve upstream tracking branches for each repository.

​
Combine filters and output raw paths

You can combine multiple flags for advanced workflows: 
# Show only dirty AND local repos, output as raw paths
dirty -dlr ~/code
Raw output mode (-r) prints one path per line with no decorations, perfect for piping to other commands: 
libs/ui-kit
tools/scripts

​
Example workflow

Here’s a typical workflow using Dirty: 
# Check what repos have uncommitted work
dirty -d ~/projects

# Review the output and navigate to a specific repo
cd ~/projects/apps/dashboard

# Handle the uncommitted changes
git add .
git commit -m "Complete feature implementation"

# Find repos that need remotes configured
dirty -l ~/projects
Use the raw output mode with shell scripts to automate operations across multiple repositories, like batch committing or adding remotes.

​
Next steps

For detailed information about all available options and flags, check out these guides:

Basic Usage

Learn the fundamentals of scanning directories

Filtering

Filter results to show only dirty or local repos

Command Reference

Complete reference for all flags and options

Scripting Guide

Use Dirty in your automation scripts

Build docs developers (and LLMs) love

Get started for freeTalk to us