Skip to main content
This page provides detailed documentation for all available flags in the dirty CLI tool.

​
Positional arguments

​
path
string
required
Directory to scan for git repositories. The tool will recursively search for .git folders up to the specified depth.
dirty ~/code
dirty /Users/john/projects
dirty .

​
Flags

​
Search depth

​
--depth
number
default:"3"
Short form: -LMaximum directory depth to search for repositories. Depth 0 checks only the specified path, depth 1 checks immediate subdirectories, and so on.
# Only check immediate subdirectories
dirty -L 1 ~/code

# Deep search up to 5 levels
dirty -L 5 ~/projects
Note: The search stops when a .git folder is found, so nested repositories within a repository are not scanned.

​
Filtering

​
--dirty
boolean
default:"false"
Short form: -dOnly show repositories with uncommitted changes. This includes both tracked modified files and untracked files.
# Find all dirty repos
dirty -d ~/code
Useful for finding repositories with work in progress before switching contexts.
​
--local
boolean
default:"false"
Short form: -lOnly show repositories with no remotes configured (local-only repositories).
# Find repos with no remotes
dirty -l ~/code
Useful for identifying experimental or local-only projects that may need to be backed up or pushed to a remote.
​
--include-unpushed
boolean
default:"false"
Short form: -uInclude unpushed commit information in the output. Shows how many commits the current branch is ahead of its upstream tracking branch.
# Show repos with unpushed commits
dirty -u ~/code
Example output with unpushed commits:
 * apps/dashboard [↑3]
   apps/storefront
 * libs/ui-kit [local]
Performance note: This flag requires resolving the upstream tracking branch for each repository, which is slower than the default behavior. Only use this flag when you need to check for unpushed commits.

​
Output format

​
--raw
boolean
default:"false"
Short form: -rOutput raw repository paths only, one per line, with no decorations or summary. Useful for piping to other commands.
# Raw output for piping
dirty -r ~/code

# Example: open all dirty repos in VS Code
dirty -dr ~/code | xargs -I {} code {}
Raw output example:
apps/dashboard
libs/ui-kit
services/auth
tools/scripts

​
Flag combinations

Flags can be combined to create powerful workflows:

​
Find dirty local-only repos

dirty -dl ~/code
Shows repositories that have both uncommitted changes AND no remotes configured. Useful for finding work that needs to be committed and potentially pushed to a new remote.

​
Export dirty repos for scripting

dirty -dr ~/code | while read repo; do
  echo "Processing $repo"
  # Add your custom logic here
done
Combines the dirty filter with raw output for easy processing in shell scripts.

​
Quick shallow scan

dirty -L 1 ~/code
Scans only immediate subdirectories for faster results when you have a flat project structure.

​
Complete status check

dirty -u ~/code
Shows all repositories with full status including uncommitted changes, local-only status, and unpushed commits. More comprehensive but slower due to upstream branch resolution.

Build docs developers (and LLMs) love

Get started for freeTalk to us