shell-cmd

High-Level Flow

1. Parse command-line options and positional arguments.
2. Recursively walk the target directory.
3. For each file whose full path matches the regex:
   • Substitute placeholders in the command template.
   • Fork a child process and execute the command via the configured shell (/bin/bash by default).
4. If --list-all is set, collect all matched paths into a list via fill_list(), then run the command once with %0 expanded to all paths joined by spaces.

Argument Parsing

shell-cmd uses a custom header-only argument parser (argz.hpp). It separates options (short like -n or long like --dry-run) from positional arguments. All options support both forms. The positional arguments are, in order:

If fewer than three positional arguments are given, the program prints an error and the help text.

Directory Traversal

The function add_directory() walks the tree using std::filesystem::directory_iterator.

• Hidden files/directories (names starting with .) are skipped by default. Pass -a to include them.
• Depth limiting — if -d N is specified, recursion stops after N levels (0 = only the given directory).
• Permission errors are handled gracefully; inaccessible directories produce an error and exit.
• Symlinks are not explicitly followed — standard directory_iterator behavior applies.

Placeholder Substitution

If the full path contains spaces, %1 is automatically wrapped in double quotes.

Command Execution

Commands are executed through a custom System() function rather than the standard library’s system():

1. Forks a child process.
2. Blocks SIGCHLD and ignores SIGINT/SIGQUIT in the parent so it isn’t accidentally killed by Ctrl+C.
3. Runs the command via execl("/bin/bash", "bash", "-c", command, …) in the child (or the shell specified by --shell).
4. Waits for the child to finish, then restores signal masks.

This prevents interrupted batch operations from leaving the parent in a bad state.

1. Count Lines of Code

See line counts for every .py file in your project:

shell-cmd . "wc -l %1" ".*\.py$"

Sample output:

  42 ./src/main.py
 118 ./src/utils.py
  27 ./tests/test_main.py

2. Preview Before You Act (Dry-Run)

Auto-format all C/C++ source files, but first verify what would run:

shell-cmd -n ./src "clang-format -i %1" ".*\.(c|cpp|h|hpp)$"

Output (nothing is executed):

clang-format -i ./src/main.cpp
clang-format -i ./src/parser.hpp
clang-format -i ./src/utils.c

When satisfied, remove -n to actually format:

shell-cmd ./src "clang-format -i %1" ".*\.(c|cpp|h|hpp)$"

3. Batch Resize Photos

Resize every JPEG in your photo library to 1920×1080 using ImageMagick:

shell-cmd ~/Photos "convert %1 -resize 1920x1080 /tmp/resized/%0" ".*\.jpe?g$"

• %1 → /home/you/Photos/vacation/sunset.jpg (the source)
• %0 → sunset.jpg (used to name the output file)

4. Back Up Log Files

Copy all .log files to a backup folder, preserving filenames:

shell-cmd /var/log "cp %1 %2/%0" ".*\.log$" /mnt/backup/logs

• %1 → full path to each log file
• %2 → /mnt/backup/logs (the extra argument)
• %0 → the filename only

5. Search for TODO Comments

shell-cmd . "grep -Hn 'TODO' %1" ".*\.(js|ts|py|cpp)$"

Example output:

./src/api.ts:45:    // TODO: add rate limiting
./src/db.py:112:    # TODO: handle connection timeout

6. Convert Markdown to PDF

Generate PDFs from documentation using Pandoc:

shell-cmd ~/docs "pandoc %1 -o /tmp/pdfs/%0.pdf" ".*\.md$"

7. Transcode WAV to MP3

shell-cmd ~/recordings "ffmpeg -i %1 -b:a 192k /tmp/mp3/%0.mp3" ".*\.wav$"

8. Validate Shell Scripts

Check syntax of all .sh files with verbose output:

shell-cmd -v . "bash -n %1" ".*\.sh$"

-v prints each command as it runs:

bash -n ./deploy.sh
bash -n ./setup.sh
bash -n ./scripts/cleanup.sh

9. Extract tar.gz Archives

shell-cmd ~/Downloads "tar xzf %1 -C /tmp/extracted" ".*\.tar\.gz$"

10. Strip EXIF Metadata

Remove all metadata from images before sharing:

shell-cmd ./photos "exiftool -all= %1" ".*\.(jpg|png)$"

11. No Recursion (Current Directory Only)

shell-cmd -d 0 . "cat %1" ".*\.txt$"

12. Include Hidden Config Files

shell-cmd -a ~ "cat %1" ".*\.bashrc|.*\.zshrc"

13. Combine Multiple Options

Preview commands, include hidden files, limit depth to 2 levels:

shell-cmd -n -a -d 2 ~ "wc -l %1" ".*rc$"

14. Compile Every C File

shell-cmd ./src "gcc -c %1 -o /tmp/%0.o" ".*\.c$"

• %1 — gives gcc the full source path
• %0.o — names the output object file after the source filename

15. Sign RPM Packages

shell-cmd ./packages "rpm --addsign %1" ".*\.rpm$"

16. Multiple Extra Arguments

shell-cmd . "cp %1 %2/%0 && echo 'copied to %3'" ".*\.conf$" /backup user@host

• %2 → /backup
• %3 → user@host

The program validates that every extra argument has a corresponding placeholder. If one is missing, shell-cmd exits with an error.

17. Find Large Files

List all files over 10 MB:

shell-cmd . "ls -lh %1" ".*" --size +10M

Short form: -s +10M

18. Delete Old Temp Files (Dry-Run)

Preview deleting .tmp files older than 30 days:

shell-cmd --dry-run /tmp "rm %1" ".*\.tmp$" --mtime +30

19. Find Executable Files

Find files with permission 755:

shell-cmd . "echo %1" ".*" --perm 755 --type f

20. List Files Owned by a User

shell-cmd /etc "echo %1" ".*\.conf$" --user root

21. Find Files by Group

shell-cmd /var/www "echo %1" ".*" --group www-data

22. List Only Directories

shell-cmd . "echo %1" ".*src.*" --type d

23. Find Symlinks

shell-cmd /usr/local "ls -la %1" ".*" --type l

24. Combine Multiple Filters

Find large .log files modified in the last 7 days, owned by syslog:

shell-cmd /var/log "wc -l %1" ".*\.log$" -s +1M -m -7 -u syslog

25. Long-Form Options in Scripts

All flags work with --long form for readability:

shell-cmd --verbose --size +5K --type f --depth 2 ./src "wc -l %1" ".*\.(cpp|hpp)$"

26. List All Matches

Collect all matched .cpp files and pass them to a single wc -l invocation:

shell-cmd -l . "wc -l %0" ".*\.cpp$"

Instead of running wc once per file, --list-all gathers every match and runs the command once with %0 replaced by the space-joined list of paths.

27. Exclude Patterns

Skip node_modules and .git directories when counting TypeScript lines:

shell-cmd -x "node_modules|\.git" . "wc -l %1" ".*\.ts$"

28. Basename & Extension Placeholders

Convert WAV files to MP3, using %b for the output name without extension:

shell-cmd ~/music "ffmpeg -i %1 /tmp/mp3/%b.mp3" ".*\.wav$"

Organize files by extension:

shell-cmd -n . "mkdir -p /tmp/by-ext/%e && cp %1 /tmp/by-ext/%e/%0" ".*"

29. Parallel Execution

Resize images using 4 parallel jobs:

shell-cmd -j 4 ./images "convert %1 -resize 800x600 /tmp/thumbs/%0" ".*\.jpg$"

30. Confirm Mode

Interactively confirm before each destructive action:

shell-cmd -c /tmp "rm %1" ".*\.bak$"

Output: Execute: rm /tmp/old.bak ? [y/N]

31. Stop on Error

Compile all C files and stop at the first failure:

shell-cmd -e ./src "gcc -c %1 -o /tmp/%b.o" ".*\.c$"

32. Summary Statistics

A summary is automatically printed when using verbose/dry-run or when any command fails:

shell-cmd -v . "wc -l %1" ".*\.py$"
# Summary: 12 matched, 12 run, 0 failed

33. Glob Mode

Use --glob / -b to write familiar wildcard patterns instead of regex. * matches anything, ? matches a single character, and special regex characters are auto-escaped:

shell-cmd --glob . "echo %1" "*.cpp"

Combine with --regex-match to match the full path using glob syntax:

shell-cmd --glob --regex-match . "echo %1" "*cmake"

34. Glob Exclude

By default, -x / --exclude takes a regex pattern. Add -i / --glob-exclude to treat it as a glob instead:

# Exclude using glob pattern
shell-cmd --glob -x "build*" --glob-exclude . "echo %1" "*.cpp"

# Exclude using regex (default, no -i needed)
shell-cmd --glob -x "build|CMakeFiles|third_party" . "echo %1" "*.cpp"

This is useful when you want consistent glob syntax for both the search pattern and the exclude pattern.

Expression Grammar

Expressions are built from functions, boolean operators, and parentheses:

Operator precedence (highest to lowest): not, and, or. Use parentheses to override.

35. Match C++ Files, Exclude Build Directories

shell-cmd . "echo %1" \
  --expr '(glob("*.cpp") or glob("*.hpp")) and not regex("build|CMakeFiles")'

This combines glob matching for file extensions with regex exclusion of build paths — something that normally requires two separate flags (--glob + -x).

36. Single Function Expression

Expressions work with just one function too — equivalent to passing a regex positional argument:

shell-cmd . "wc -l %1" --expr 'regex("\.py$")'

37. Nested Boolean Logic

Match Python or Rust source files, but exclude test files and anything in a vendor directory:

shell-cmd . "echo %1" \
  --expr '(glob("*.py") or glob("*.rs")) and not glob("*test*") and not regex("vendor")'

38. Full-Path Match in an Expression

Use regex_match() inside an expression for full-path anchoring:

shell-cmd . "echo %1" --expr 'regex_match("\\./src/.*\\.cpp")'

This matches only .cpp files directly under ./src/.

39. Combine --expr with -x Exclude and Metadata Filters

--expr replaces the search pattern, but all other options work alongside it:

shell-cmd -x "node_modules" --size +1K --type f . "wc -l %1" \
  --expr 'glob("*.ts") or glob("*.tsx")'