{"id":50333098,"url":"https://github.com/ddiidev/unix-emulators-win","last_synced_at":"2026-05-29T11:01:39.212Z","repository":{"id":354938145,"uuid":"1226111014","full_name":"Ddiidev/unix-emulators-win","owner":"Ddiidev","description":"Collection of 16 UNIX utilities (ls, cat, grep, rm, mkdir, touch, cp, mv, find, pwd, which, head, tail, sort, uniq, xargs) rewritten in V for Windows. POSIX compliant, with support for Windows paths and CRLF. Designed for use with rtk, a UNIX shell command bridge for Windows.","archived":false,"fork":false,"pushed_at":"2026-05-27T02:02:42.000Z","size":118,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T03:21:35.909Z","etag":null,"topics":["unix","windows"],"latest_commit_sha":null,"homepage":"","language":"V","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ddiidev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.MD","dco":null,"cla":null}},"created_at":"2026-05-01T01:42:29.000Z","updated_at":"2026-05-27T02:02:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Ddiidev/unix-emulators-win","commit_stats":null,"previous_names":["ddiidev/unix-emulators-win"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Ddiidev/unix-emulators-win","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ddiidev%2Funix-emulators-win","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ddiidev%2Funix-emulators-win/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ddiidev%2Funix-emulators-win/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ddiidev%2Funix-emulators-win/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ddiidev","download_url":"https://codeload.github.com/Ddiidev/unix-emulators-win/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ddiidev%2Funix-emulators-win/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33648534,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["unix","windows"],"created_at":"2026-05-29T11:01:37.747Z","updated_at":"2026-05-29T11:01:39.206Z","avatar_url":"https://github.com/Ddiidev.png","language":"V","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🛠️ Unix Executable Emulators for Windows\n\n\u003e **16 standalone UNIX utilities** written in [V](https://vlang.io/) — bridging the gap between Windows and UNIX shell environments for AI agents and developer tools.\n\u003e\n\u003e 🇧🇷 [Leia em português](README.pt-br.md)\n\n![Tools](https://img.shields.io/badge/tools-16-blue)\n![Language](https://img.shields.io/badge/language-V-5D87BF)\n![Platform](https://img.shields.io/badge/platform-Windows-0078D6)\n![Tests](https://img.shields.io/badge/tests-55+-green)\n\n---\n\n## Table of Contents\n\n- [Why This Exists](#why-this-exists)\n- [Quick Start](#quick-start)\n- [Tool Reference](#tool-reference)\n  - [File Listing \u0026 Inspection](#file-listing--inspection)\n  - [File Content](#file-content)\n  - [Search \u0026 Filter](#search--filter)\n  - [File Operations](#file-operations)\n  - [Utilities](#utilities)\n- [Argument Policy](#argument-policy)\n- [Testing](#testing)\n- [Architecture](#architecture)\n- [Building](#building)\n- [RTK on Windows — Agent Prompt Template](#rtk-on-windows--agent-prompt-template)\n\n---\n\n## Why This Exists\n\nWindows lacks native equivalents of standard UNIX commands (`ls`, `grep`, `find`, etc.). While PowerShell provides aliases, they are incompatible with external programs that expect real executables on `PATH`.\n\n### Built for [rtk](https://github.com/rtk-ai/rtk/)\n\nThe core motivation is **token economy for AI agents**. When an LLM calls PowerShell cmdlets like `Select-String` or `Get-ChildItem`, the output is verbose, object-formatted, and often hundreds of lines. This wastes thousands of tokens per call — tokens you pay for.\n\nThese executables produce **dense, UNIX-style plain-text output** consumable in a single glance. Paired with [rtk](https://github.com/rtk-ai/rtk/) (AI proxy), they let agents execute CLI operations with short pipelines like:\n\n```bash\nrtk grep -n \"pattern\" path | rtk head -n 80\nrtk findd ./src -name \"*.ts\" | xargs grep \"TODO\" | rtk head -n 200\n```\n\n**To get the most out of this setup**, use the agent system prompt provided in **[AGENTS_SUGGESTION_FOR_RTK.md](AGENTS_SUGGESTION_FOR_RTK.md)**. It enforces mandatory `rtk` wrappers, forbids verbose PowerShell cmdlets, and auto-excludes binary/dependency directories — all designed to minimize token waste.\n\nThe binaries:\n\n1. **Work as real executables** — callable from any shell, script, or external tool (e.g., `rtk`, AI agents like Codex/Gemini)\n2. **Return POSIX exit codes** — `0` for success, `1` for no match/error, `2` for usage errors\n3. **Support common GNU/UNIX flags** — progressively implementing the most-used flags\n4. **Handle Windows paths** — backslash/forward-slash normalization, `PATHEXT` support\n5. **Auto-exclude noisy directories** — `node_modules`, `.git`, `vendor`, etc. are skipped by default in recursive scans\n6. **Auto-detect literal patterns** — grep bypasses the regex engine when the pattern has no meta-characters, cutting RAM from GBs to MBs\n\n---\n\n## Quick Start\n\n### Prerequisites\n- [V compiler](https://vlang.io/) installed and on PATH\n\n### Build All\n```powershell\ncd executables\n.\\build.bat\n# or\npowershell -File .\\build.ps1\n```\n\n### Build Single Tool\n```powershell\ncd executables\\exe_ls\n.\\build.bat\n```\n\nBinaries are compiled to the project root (two levels above each `exe_\u003ctool\u003e` directory). Place them in a directory on your `PATH`.\n\n### First Usage\n```powershell\nls -la .\ngrep -rn \"TODO\" ./src --include=\"*.v\"\nfind . -iname \"*.txt\" -type f\ncat -n file.txt | head -n 20\nsort data.csv | uniq -c\n```\n\n---\n\n## Tool Reference\n\n### File Listing \u0026 Inspection\n\n#### `ls` — List directory contents\n```\nls [OPTIONS] [FILE...]\n```\n\n| Flag | Description |\n|------|-------------|\n| `-a`, `--all` | Show hidden files (starting with `.`) |\n| `-A`, `--almost-all` | Like `-a` but exclude `.` and `..` |\n| `-l`, `--long` | Long listing format with permissions, size, date |\n| `-h`, `--human-readable` | Human-readable sizes (1K, 234M, 2G) with `-l` |\n| `--si` | Like `-h` but use powers of 1000 |\n| `-r`, `--reverse` | Reverse sort order |\n| `-R`, `--recursive` | List subdirectories recursively |\n| `-1`, `--one-line` | One file per line |\n| `-m`, `--commas` | Comma-separated list |\n| `-S` | Sort by file size (largest first) |\n| `-t` | Sort by modification time (newest first) |\n| `-v` | Natural sort of version numbers (`file2` before `file10`) |\n| `-X` | Sort alphabetically by extension |\n| `-U` | Do not sort (directory order) |\n| `-F`, `--classify` | Append indicator (`*/=\u003e@|`) to entries |\n| `-p`, `--slash` | Append `/` to directories |\n| `--group-directories-first` | Group directories before files |\n| `-i`, `--inode` | Print inode number |\n| `-s`, `--size` | Print allocated size in blocks |\n| `-n`, `--numeric-uid-gid` | Numeric user/group IDs |\n| `-g`, `--no-owner` | Like `-l` but hide owner |\n| `-G`, `--no-group` | Hide group in long listing |\n| `-o` | Like `-l` but hide group |\n| `-d`, `--directory` | List directories themselves, not contents |\n| `-Q`, `--quote-name` | Enclose names in double quotes |\n| `-b`, `--escape` | C-style escapes for non-graphic characters |\n| `--color=WHEN` | Colorize output (`always`, `auto`, `never`) |\n| `--time-style=STYLE` | Time format (`full-iso`, `long-iso`, `iso`, `locale`) |\n| `--full-time` | Like `-l --time-style=full-iso` |\n| `-u` | Sort/show access time |\n| `-c` | Sort/show status change time |\n\n---\n\n#### `pwd` — Print working directory\n```\npwd [OPTIONS]\n```\n\n| Flag | Description |\n|------|-------------|\n| `-L` | Use PWD from environment (default) |\n| `-P` | Resolve all symlinks (stub) |\n\nOutputs forward-slash paths for UNIX compatibility.\n\n---\n\n#### `which` — Locate a command\n```\nwhich [OPTIONS] COMMAND...\n```\n\n| Flag | Description |\n|------|-------------|\n| `-a`, `--all` | Print all matching pathnames |\n\nSearches `PATH` directories and respects `PATHEXT` on Windows.\n\n---\n\n### File Content\n\n#### `cat` — Concatenate and display files\n```\ncat [OPTIONS] [FILE...]\n```\n\n| Flag | Description |\n|------|-------------|\n| `-n`, `--number` | Number all output lines |\n| `-b`, `--number-nonblank` | Number non-empty lines only (overrides `-n`) |\n| `-s`, `--squeeze-blank` | Suppress repeated empty lines |\n| `-E`, `--show-ends` | Display `$` at end of each line |\n| `-T`, `--show-tabs` | Display TAB as `^I` |\n| `-A`, `--show-all` | Equivalent to `-vET` |\n\nReads from stdin when no file is specified or file is `-`.\n\n---\n\n#### `head` — Output first part of files\n```\nhead [OPTIONS] [FILE...]\n```\n\n| Flag | Description |\n|------|-------------|\n| `-n K`, `--lines=K` | Print first K lines (default: 10) |\n| `-c K`, `--bytes=K` | Print first K bytes |\n| `-v`, `--verbose` | Always print file name headers |\n| `-q`, `--quiet` | Never print file name headers |\n\n---\n\n#### `tail` — Output last part of files\n```\ntail [OPTIONS] [FILE...]\n```\n\n| Flag | Description |\n|------|-------------|\n| `-n K`, `--lines=K` | Output last K lines (default: 10) |\n| `-f`, `--follow` | Output appended data as file grows |\n| `-s N`, `--sleep-interval=N` | Sleep N seconds between follow iterations |\n| `-v`, `--verbose` | Always print file name headers |\n| `-q`, `--quiet` | Never print file name headers |\n\n\u003e **Performance**: Uses seek-from-end approach — handles multi-GB files without loading them into memory.\n\n---\n\n### Search \u0026 Filter\n\n#### `grep` — Search for patterns in files\n```\ngrep [OPTIONS] PATTERN [FILE...]\n```\n\n| Flag | Description |\n|------|-------------|\n| `-i`, `--ignore-case` | Case-insensitive matching |\n| `-v`, `--invert-match` | Select non-matching lines |\n| `-n`, `--line-number` | Print line numbers |\n| `-c`, `--count` | Print only match count per file |\n| `-l`, `--files-with-matches` | Print only filenames with matches |\n| `-L`, `--files-without-matches` | Print only filenames without matches |\n| `-r`, `-R`, `--recursive` | Search directories recursively |\n| `-w`, `--word-regexp` | Match whole words only |\n| `-x`, `--line-regexp` | Match whole lines only |\n| `-F`, `--fixed-strings` | Treat pattern as literal string |\n| `-o`, `--only-matching` | Show only the matched part of lines |\n| `-H`, `--with-filename` | Print filename with output |\n| `-h`, `--no-filename` | Suppress filename prefix |\n| `-A N`, `--after-context=N` | Print N lines after each match |\n| `-B N`, `--before-context=N` | Print N lines before each match |\n| `-C N`, `--context=N` | Print N lines of context (before + after) |\n| `-m N`, `--max-count=N` | Stop after N matches per file |\n| `-q`, `--quiet` | Suppress all output |\n| `-s`, `--silent` | Suppress error messages |\n| `--color=WHEN` | Colorize matches (`always`, `auto`, `never`) |\n| `--exclude=GLOB` | Skip files matching GLOB |\n| `--exclude-dir=DIR` | Skip directories matching DIR |\n| `--include=GLOB` | Search only files matching GLOB |\n\n\u003e **Performance**: Auto-detects literal patterns to bypass the regex engine, circular buffer for context lines (O(1) vs O(n) for before-context), auto-excludes `node_modules`/`.git`/`vendor`/etc in recursive scans, iterative BFS-based directory traversal.\n\n---\n\n#### `find` — Search for files in directory hierarchy\n```\nfind [PATH...] [OPTIONS]\n```\n\n| Flag | Description |\n|------|-------------|\n| `-name PATTERN` | Match filename (case-sensitive glob) |\n| `-iname PATTERN` | Match filename (case-insensitive glob) |\n| `-type TYPE` | Filter by type (`f` = file, `d` = directory) |\n| `-empty` | Match empty files/directories |\n| `-maxdepth N` | Descend at most N levels |\n| `-delete` | Delete matched files |\n| `-o`, `-or` | OR operator between filter groups |\n\nSupports combining multiple filters with `-o` (OR logic). Glob patterns use `*` and `?`.\n\n\u003e **Performance**: Regex patterns are pre-compiled once at startup, not per-file.\n\n---\n\n#### `sort` — Sort lines of text files\n```\nsort [OPTIONS] [FILE...]\n```\n\n| Flag | Description |\n|------|-------------|\n| `-r`, `--reverse` | Reverse sort order |\n| `-n`, `--numeric-sort` | Compare by numerical value |\n| `-u`, `--unique` | Output only unique lines |\n\n---\n\n#### `uniq` — Filter adjacent duplicate lines\n```\nuniq [OPTIONS] [INPUT [OUTPUT]]\n```\n\n| Flag | Description |\n|------|-------------|\n| `-c`, `--count` | Prefix lines by occurrence count |\n| `-d`, `--repeated` | Only print duplicate lines |\n| `-u`, `--unique` | Only print unique lines |\n| `-i`, `--ignore-case` | Case-insensitive comparison |\n\n---\n\n### File Operations\n\n#### `cp` — Copy files and directories\n```\ncp [OPTIONS] SOURCE... DEST\n```\n\n| Flag | Description |\n|------|-------------|\n| `-r`, `-R`, `--recursive` | Copy directories recursively |\n| `-f`, `--force` | Force overwrite |\n| `-i`, `--interactive` | Prompt before overwrite |\n| `-n`, `--no-clobber` | Do not overwrite existing files |\n| `-v`, `--verbose` | Explain what is being done |\n\n---\n\n#### `mv` — Move/rename files\n```\nmv [OPTIONS] SOURCE... DEST\n```\n\n| Flag | Description |\n|------|-------------|\n| `-f`, `--force` | Do not prompt before overwriting |\n| `-i`, `--interactive` | Prompt before overwrite |\n| `-n`, `--no-clobber` | Do not overwrite existing files |\n| `-v`, `--verbose` | Explain what is being done |\n\n---\n\n#### `rm` — Remove files and directories\n```\nrm [OPTIONS] FILE...\n```\n\n| Flag | Description |\n|------|-------------|\n| `-r`, `-R`, `--recursive` | Remove directories recursively |\n| `-f`, `--force` | Ignore nonexistent files, never prompt |\n| `-i`, `--interactive` | Prompt before every removal |\n| `-v`, `--verbose` | Explain what is being done |\n| `-d`, `--dir` | Remove empty directories |\n\n---\n\n#### `mkdir` — Create directories\n```\nmkdir [OPTIONS] DIRECTORY...\n```\n\n| Flag | Description |\n|------|-------------|\n| `-p`, `--parents` | Create parent directories as needed |\n| `-v`, `--verbose` | Print message for each created directory |\n\n---\n\n#### `touch` — Update file timestamps\n```\ntouch [OPTIONS] FILE...\n```\n\n| Flag | Description |\n|------|-------------|\n| `-c`, `--no-create` | Do not create any files |\n| `-a` | Change only the access time |\n| `-m` | Change only the modification time |\n\n---\n\n### Utilities\n\n#### `xargs` — Build and execute commands from stdin\n```\nxargs [OPTIONS] [COMMAND [ARGS...]]\n```\n\n| Flag | Description |\n|------|-------------|\n| `-0`, `--null` | Input items separated by NUL (for `find -print0`) |\n| `-I REPLACE` | Replace REPLACE in args with each input item |\n| `-n MAX` | Use at most MAX arguments per command |\n| `-t`, `--verbose` | Print commands before execution |\n| `-r`, `--no-run-if-empty` | Don't run command if stdin is empty |\n\n**Examples:**\n```bash\nfind . -name \"*.txt\" | xargs grep \"TODO\"\nfind . -print0 | xargs -0 wc -l\necho file1 file2 | xargs -I {} cp {} /backup/\nls *.log | xargs -n 2 echo \"Batch:\"\n```\n\n---\n\n## Argument Policy\n\nFor any flag that is **not yet implemented**, the tools return a standardized error message:\n\n```\nTODO (UNIX WINDOWS): THIS ARGUMENT HAS NOT YET BEEN IMPLEMENTED.\nUSE AN ALTERNATIVE METHOD, AS THE \"ls\" COMMAND DOES NOT YET HAVE THIS ARGUMENT \"-la\".\n```\n\nThis message is designed for AI agents to understand and use alternative approaches.\n\n---\n\n## Testing\n\nEach tool has integration tests in its `tests/` directory:\n\n```powershell\n# Run tests for a specific tool\ncd executables\\exe_grep\nv test tests/\n\n# Run all tests\nGet-ChildItem -Directory exe_* | ForEach-Object {\n    Write-Host \"Testing $($_.Name)...\"\n    Push-Location $_.FullName\n    v test tests/\n    Pop-Location\n}\n```\n\nTests use `os.execute()` to run the compiled binary and verify exit codes and output. New features and optimizations require new tests — see [AGENTS.md](AGENTS.MD) for the full testing policy.\n\n---\n\n## Architecture\n\n```\nexecutables/\n├── AGENTS.MD          # Agent-facing documentation \u0026 testing policy\n├── README.md          # This file\n├── README.pt-br.md    # Brazilian Portuguese version\n├── build.ps1          # Build all tools\n├── build.bat          # Wrapper for build.ps1\n├── exe_ls/            # Each tool in its own directory\n│   ├── main.v         # Entry point \u0026 argument parsing\n│   ├── lister.v       # Core logic (directory listing)\n│   ├── filedata.v     # Data structures\n│   ├── options.v      # Options struct\n│   ├── utils.v        # Utility functions\n│   ├── build.bat      # Individual build script\n│   └── tests/\n│       └── ls_test.v  # Integration tests\n├── exe_grep/\n│   ├── main.v\n│   ├── matcher.v      # Regex/fixed-string matching engine\n│   ├── processor.v    # File processing \u0026 output\n│   ├── filters.v      # --exclude/--include handling\n│   ├── options.v\n│   └── tests/\n│       ├── grep_test.v\n│       ├── context_test.v\n│       ├── exclude_test.v\n│       ├── literal_test.v\n│       └── autoexclude_test.v\n└── ...                # 14 more tools following the same pattern\n```\n\n### Conventions\n\n- **Directory naming**: `exe_\u003ccommand\u003e` (e.g., `exe_ls`, `exe_grep`)\n- **Build output**: Each `build.bat` compiles to `../../\u003ccommand\u003e.exe` (the `bin/` root)\n- **Build flags**: All builds use `-prod` for optimized release binaries\n- **Module**: All files use `module main`\n- **Options**: Parsed with V's `flag` module, stored in an `Options` struct\n\n---\n\n## Building\n\n### Single Tool\n```powershell\ncd executables\\exe_ls\nv -prod -o \"..\\..\\ls.exe\" .\n```\n\n### All Tools\n```powershell\ncd executables\n.\\build.ps1\n```\n\n### Development (fast, no optimizations)\n```powershell\ncd executables\\exe_ls\nv -o \"..\\..\\ls.exe\" .\n```\n\n---\n\n## RTK on Windows — Agent Prompt Template\n\nTo get the most out of these tools with [rtk](https://github.com/rtk-ai/rtk/), use the agent system prompt provided in **[AGENTS_SUGGESTION_FOR_RTK.md](AGENTS_SUGGESTION_FOR_RTK.md)**. It enforces:\n\n- **MANDATORY** use of `rtk` wrappers for CLI operations on Windows\n- **FORBIDDEN** use of native PowerShell cmdlets (`Select-String`, `Get-Content`, `Get-ChildItem`) for file/text operations\n- Short UNIX-style pipelines with `rtk grep ... | rtk head ...`\n- Targeted paths/extensions over broad recursive scans from `.`\n- `findd | xargs grep` to narrow by directory and file type before running `grep`\n- Auto-exclusion of binary files, `node_modules`, `.git`, `build/`, `dist/`, etc.\n- Auto-exclusion of binary extensions: `*.exe`, `*.dll`, `*.sqlite`, `*.png`, `*.pdf`, `*.zip`, etc.\n\nSee the file for the full ready-to-copy prompt and examples.\n\n\u003e **Why this matters**: PowerShell cmdlets produce verbose, object-formatted output that wastes thousands of AI tokens per call. These UNIX-style tools output dense plain text — a single `rtk grep ... | rtk head -n 80` can replace a 200-line PowerShell output with 3-5 lines the LLM can consume instantly.\n\n---\n\n## License\n\nInternal tooling — part of the `rtk` ecosystem.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddiidev%2Funix-emulators-win","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fddiidev%2Funix-emulators-win","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddiidev%2Funix-emulators-win/lists"}