File Ops

File Operations

Before running any file system command, detect the user's OS and load the matching reference for platform-specific syntax:

• Linux — references/linux.md (GNU coreutils, grep, find, ripgrep, fd)
• macOS — references/macos.md (BSD find/stat/sed, Spotlight, Homebrew tools)
• Windows — references/windows.md (PowerShell: Get-ChildItem, Select-String, Get-Content)

OS detection:

uname -s 2>/dev/null || echo Windows

Path specification

Relative vs absolute

| Syntax | Meaning | |--------|---------| | . | Current working directory | | .. | Parent directory | | ./src | src/ relative to cwd | | ../../config | Two levels up, then into config/ | | /home/user/project | Absolute path (Unix) | | C:\Users\user\project | Absolute path (Windows) | | ~/Documents | Home directory shortcut (Unix shells expand ~) |

Quoting paths with spaces

Paths containing spaces, parentheses, or special characters must be quoted:

• "./my project/src" — double quotes (variables expand inside)
• './my project/src' — single quotes (literal, no expansion)
• ./my\ project/src — backslash escaping per character

Trailing slash behavior

• path/to/dir — refers to the directory itself
• path/to/dir/ — refers to the contents (relevant for rsync, cp -r, tab completion)

Glob patterns

Globs are shell-level filename matching patterns. They do NOT use regex syntax.

| Pattern | Matches | Does not match | |---------|---------|----------------| | * | any sequence of characters (except /) | nothing across directories | | ? | exactly one character | empty string | | [abc] | one of a, b, or c | d, ab | | [a-z] | one lowercase letter | A, 1 | | [!abc] or [^abc] | any char except a, b, c | a | | ** | any depth of directories (in tools that support it) | — |

Common glob examples

| Task | Pattern | |------|---------| | All Rust source files | *.rs | | All TOML configs | *.toml | | All test files | *_test.* or test_*.* | | All hidden files | .* | | All files in src/ subtree | src/**/* (requires ** support) | | Images by extension | *.{png,jpg,svg} (brace expansion, bash/zsh) | | Single-char extension | *.? | | Files starting with config | config* | | Logs with date suffix | app-2025-??-??.log |

Brace expansion (bash/zsh only, not POSIX)

{a,b,c} expands to multiple alternatives before glob matching:

• *.{rs,toml} expands to *.rs *.toml
• {src,tests}/**/*.rs expands to src/**/*.rs tests/**/*.rs
• file.{bak,orig,tmp} expands to file.bak file.orig file.tmp

Regex patterns for content search

Regex is used for searching inside file contents (grep, ripgrep, Select-String). Not to be confused with globs.

Basic syntax

| Pattern | Matches | |---------|---------| | . | any single character | | \d | digit [0-9] (PCRE/ripgrep; use [0-9] in POSIX) | | \w | word character [a-zA-Z0-9_] | | \s | whitespace (space, tab, newline) | | \b | word boundary | | ^ | start of line | | $ | end of line | | [abc] | character class | | [^abc] | negated character class | | (a\|b) | alternation | | (...) | grouping |

Quantifiers

| Pattern | Meaning | |---------|---------| | * | zero or more of preceding | | + | one or more of preceding | | ? | zero or one of preceding | | {3} | exactly 3 | | {2,5} | 2 to 5 | | {3,} | 3 or more |

Common regex examples

| Task | Pattern | |------|---------| | Function definitions (Rust) | fn\s+\w+\( | | Function definitions (Python) | def\s+\w+\( | | Function definitions (JS/TS) | (function\|const\|let)\s+\w+\s*[=(] | | Import/use statements | ^(use\|import\|from)\s+ | | TODO/FIXME/HACK markers | (TODO\|FIXME\|HACK) | | IP addresses (v4, approximate) | \d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3} | | Email addresses (simple) | [\w.+-]+@[\w-]+\.[\w.]+ | | URLs | https?://[^\s"'>]+ | | Struct/class definitions | (struct\|class\|interface)\s+\w+ | | Error/panic patterns | (error\|Error\|panic\|PANIC\|unwrap\(\)) | | Environment variables | [A-Z_]{2,}=[^\s]+ | | Semantic version | \d+\.\d+\.\d+ | | Lines with trailing whitespace | \s+$ | | Empty lines | ^$ | | Lines longer than 100 chars | .{101,} | | Hex color codes | #[0-9a-fA-F]{3,8} | | SQL-like queries | (SELECT\|INSERT\|UPDATE\|DELETE)\s+ | | JSON keys | "[^"]+"\s*: |

Escaping special characters

To search for literal ., *, +, ?, (, ), [, ], {, }, |, ^, $, \ — prefix with backslash:

• Find fn() literally: fn\(\)
• Find [TODO] literally: \[TODO\]
• Find *.rs literally: \*\.rs
• Find $HOME literally: \$HOME

Directories to exclude

Common directories that should be excluded from search to avoid noise and improve performance:

| Directory | Context | |-----------|---------| | target/ | Rust build artifacts | | node_modules/ | JavaScript dependencies | | .git/ | Git internal data | | __pycache__/ | Python bytecode cache | | .venv/, venv/ | Python virtual environments | | build/, dist/ | Generic build output | | .next/, .nuxt/ | Framework build caches | | vendor/ | Vendored dependencies (Go, PHP, Ruby) | | .idea/, .vscode/ | IDE configuration | | coverage/, .nyc_output/ | Test coverage reports |

Workflow

1. Detect the OS (see command above).
2. Load the matching reference file for platform-specific command syntax.
3. Identify the operation the user needs (find, search, read, compare, etc.).
4. Prefer read-only commands. Never modify or delete files unless explicitly asked.
5. Exclude noisy directories (see table above) from search and find commands.
6. When results may be large, limit output with head, --max-count, or depth flags.
7. Present results concisely: file paths, line numbers, matched content. Summarize counts when listing many files.

Common workflows

Find and search combined

When the user says "find all files containing X", combine file finding with content search:

1. Use content search tools (ripgrep, grep) which already walk the file tree.
2. Add file type filters (-t rust, --include '*.py') to narrow scope.
3. Exclude build directories.

Investigate a codebase

1. Start with a directory listing to understand project structure.
2. Look for manifest files (Cargo.toml, package.json, pyproject.toml) to identify the tech stack.
3. Search for the specific symbol, function, or pattern the user is asking about.
4. Read the relevant files to provide context around matches.

Compare files or versions

1. Determine whether the user wants a side-by-side or unified diff.
2. Use diff -u (Unix) or Compare-Object (PowerShell) from the OS reference.
3. Highlight the key differences in your summary.

Available operations

List directory contents

Show files and directories at a given path with details (permissions, size, timestamps). Support recursive listing with depth limits.

Find files by name or pattern

Locate files by exact name, extension, glob/regex pattern. Filter by modification time, size, type (file/directory). Exclude build artifacts and VCS directories.

Search text inside files

Find lines matching a pattern across files. Support case-insensitive search, regex, context lines, file type filtering, directory exclusions, word-boundary matching, inverted matching, and match counting.

Read file contents

Display full file or specific portions: first/last N lines, line range, with line numbers.

File metadata and analysis

Determine file type/encoding, line/word/byte counts, size, disk usage. Find largest files, count files by extension.

Compare files

Show differences between two files in side-by-side or unified (patch) format.

Permissions and ownership

View and modify file permissions. Find files by owner or permission bits.

Checksums

Compute file hashes (SHA-256, MD5) for integrity verification.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bug-ops
• Source: bug-ops/zeph
• License: MIT
• Homepage: https://bug-ops.github.io/zeph/

Install and usage instructions live in the source repository linked above.