{"id":25563635,"url":"https://github.com/sky93/file-mapper","last_synced_at":"2026-02-28T03:38:09.702Z","repository":{"id":278315655,"uuid":"934179045","full_name":"sky93/file-mapper","owner":"sky93","description":"file-mapper: Combines tree and cat in one CLI for recursive project mapping and file content viewing.","archived":false,"fork":false,"pushed_at":"2025-03-03T17:25:41.000Z","size":37,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-26T03:33:14.249Z","etag":null,"topics":["cli","files","tools"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sky93.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2025-02-17T12:03:48.000Z","updated_at":"2025-03-03T17:25:35.000Z","dependencies_parsed_at":null,"dependency_job_id":"d8a24429-257e-4785-9f92-f3cb16fd2614","html_url":"https://github.com/sky93/file-mapper","commit_stats":null,"previous_names":["sky93/file-mapper"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sky93%2Ffile-mapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sky93%2Ffile-mapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sky93%2Ffile-mapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sky93%2Ffile-mapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sky93","download_url":"https://codeload.github.com/sky93/file-mapper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248538281,"owners_count":21120971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["cli","files","tools"],"created_at":"2025-02-20T20:27:00.337Z","updated_at":"2026-02-28T03:38:04.656Z","avatar_url":"https://github.com/sky93.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🕶 file-mapper\n\n**file-mapper** is a versatile CLI tool that combines the power of the Linux **`tree`** command (for hierarchical directory listings) and the **`cat`** command (for file content viewing)—all rolled into one convenient package. Recursively map out your project structure, filter files, and optionally display file contents (with features like line numbering). It's ideal for developers who want a comprehensive project overview or need to share both file structure and content with others (e.g., in code reviews or AI tools).\n\n---\n\n## Features\n\n1. **Tree or Flat**\n    - By default, `file-mapper` displays a **hierarchical tree** of your files and directories (like `tree`).\n    - Use the `--flat` flag for a **flat** listing instead.\n\n2. **Git-Tracked-Only**\n    - Restrict the output to only files that are **tracked by Git** (`--git`).\n\n3. **Include / Exclude Patterns**\n    - Filter specific file types (e.g. `--include=\"*.go,*.md\"`)\n    - Exclude directories/files (e.g. `--exclude=\".git,node_modules\"`).\n\n4. **Hidden \u0026 Binary Skips**\n    - Hidden files/directories (those starting with `.`) are **ignored by default**.\n    - Uses a naive approach to skip **binary** files.\n\n5. **Content Viewing**\n    - **Inline** content right below each file (similar to `cat`, but recursive) (`--content`).\n    - Or **separate**: list all files, then dump their contents afterward.\n    - Enable **line numbers** (`--line-numbers`) for quick reference.\n    - Show or hide content headers (`----- CONTENT START -----` / `----- CONTENT END -----`).\n\n6. **Output to File**\n    - Save your entire listing and contents to a file (`--output=out.txt`).\n\n---\n\n## Why Use file-mapper?\n\n- **One-Stop Command**: Instead of running `tree` to see the structure and then `cat` or `less` for file contents, `file-mapper` does it **all in one go**, recursively.\n- **Share With AI or Peers**: Perfect for pasting a project’s structure and file contents into ChatGPT or sending it to teammates.\n- **Saves Time**: No manual copy-pasting or multiple commands—filter, track only Git files, and see everything at a glance.\n\n---\n\n## Installation\n\n### 1. Homebrew (macOS 10.12+)\nIf you’re on macOS, you can install **file-mapper** via [Homebrew](https://brew.sh/):\n```bash\nbrew install sky93/file-mapper/file-mapper\n```\n\n### 2. Prebuilt Binaries (Windows, macOS, Linux)\nYou can download a prebuilt binary for your operating system from the [GitHub Releases](https://github.com/sky93/file-mapper/releases) page. Once downloaded, simply place the executable in your `PATH` (e.g., `/usr/local/bin` on macOS/Linux or somewhere in your `PATH` on Windows).\n\n### 3. Install via Go\nIf you have Go installed and prefer installing from source, you can do:\n```bash\ngo install github.com/sky93/file-mapper/cmd/file-mapper@latest\n```\n\u003e This command fetches and installs the latest version of **file-mapper** from the GitHub repo, placing the binary in your Go `bin` folder (usually `~/go/bin`).\n\n\u003e **Tip**: Ensure your `~/go/bin` (or the equivalent on your system) is in your `$PATH` so that you can run `file-mapper` from anywhere.\n\n---\n\n## Usage\n\nOnce installed:\n\n```bash\nfile-mapper [flags...]\n```\n\nAlternatively, if you cloned the repo locally and want to run without installing:\n\n```bash\ngit clone https://github.com/sky93/file-mapper.git\ncd file-mapper/cmd/projectMapper\ngo run main.go [flags...]\n```\n\n---\n\n### CLI Flags\n\n| Flag                | Alias | Default | Description                                                                                                       |\n|---------------------|-------|---------|-------------------------------------------------------------------------------------------------------------------|\n| `--path`            | `-p`  | `.`     | Root path to scan                                                                                                 |\n| `--include`         | `-i`  |         | Comma-separated file patterns to include (e.g. `--include=\"*.go,*.md\"`)                                           |\n| `--exclude`         | `-e`  |         | Comma-separated directories/files to exclude (e.g. `--exclude=\".git,.idea,.env\"`)                                |\n| `--git`             | `-g`  | `false` | Only list files tracked by Git                                                                                    |\n| `--content`         | `-c`  | `false` | Show file content (for text files)                                                                                |\n| `--separate-content`| `-s`  | `true`  | Print the file listing first, then all file contents afterward (instead of inline)                                |\n| `--flat`            |       | `false` | Show a flat list instead of a tree                                                                                |\n| `--output`          | `-o`  |         | Output file path (if not provided, prints to stdout)                                                              |\n| `--line-numbers`    |       | `false` | Show line numbers for file content                                                                                |\n| `--header-footer`   |       | `true`  | Print `----- CONTENT START -----` / `----- CONTENT END -----` around file content                                 |\n| `--help`            |       |         | Show help message                                                                                                 |\n| `--version`         |       |         | Print version information and exit                                                                                |\n\n---\n\n## Examples\n\n1. **Default Tree**\n   ```bash\n   file-mapper\n   ```\n    - Displays the folder/file structure in a tree.\n    - Skips hidden directories and binary files.\n\n2. **Display File Contents Inline**\n   ```bash\n   file-mapper --content\n   ```\n    - Combines tree + `cat` for each file, printing content right below the file.\n\n3. **Only Git-Tracked Files**\n   ```bash\n   file-mapper --git\n   ```\n    - Recursively traverses your directories, showing **only** files tracked by Git.\n\n4. **Tree + Separate Content**\n   ```bash\n   file-mapper --content --separate-content\n   ```\n    - Prints the tree, then appends file contents at the end.\n\n5. **Flat Listing**\n   ```bash\n   file-mapper --flat\n   ```\n    - Shows a simple list of files/directories.\n\n6. **Include/Exclude Patterns**\n   ```bash\n   file-mapper --include=\"*.go,*.txt\" --exclude=\".git,.idea,node_modules\"\n   ```\n\n7. **Output to a File**\n   ```bash\n   file-mapper --output=map.txt\n   ```\n    - Saves the entire listing and optional content to `map.txt`.\n\n8. **Line Numbers + Content**\n   ```bash\n   file-mapper --content --line-numbers\n   ```\n\n---\n\n## Contributing\n\nAll contributions are welcome! If you have any feature requests, bug reports, or ideas, feel free to open an [issue](https://github.com/sky93/file-mapper/issues) or submit a pull request.\n\n---\n\n## License\n\nPlease see the [LICENSE](https://github.com/sky93/file-mapper/blob/main/LICENSE) file for details.\n\n---\n\nHappy mapping with **file-mapper**! If you find it useful, give it a star on [GitHub](https://github.com/sky93/file-mapper).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsky93%2Ffile-mapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsky93%2Ffile-mapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsky93%2Ffile-mapper/lists"}