🗂️ fsmap — Visualize Folder Structures from Local or GitHub Repos

fsmap is a powerful CLI tool that scans any directory (local or remote GitHub repo) and visualizes its folder structure in a clean, tree-like format.

Supports output as text, markdown, JSON, and even integrates file size, modified dates, and Git status.

📦 Features

• 📁 Visualize any local folder structure
• 🌍 Fetch and display GitHub repo structure via --repo
• 🧹 Smart one-repo caching system (reuse if same repo, delete if not)
• 💾 Show file sizes (--show-size)
• 🕒 Show last modified dates (--show-date)
• 🧑‍💻 Show Git status (--show-git)
• 📝 Output as: text (default), markdown, JSON, or HTML
• 📄 Save output to a file
• 🔍 Works recursively with depth control

🛠️ Installation

(Global)

npm install -g fsmap-cli

(Local)

npm install -D fsmap-cli

🚀 Usage

(Global)

fsmap [path] [options]

(Local)

npx fsmap [path] [options]

By default, it scans the current directory (.).

📁 Scan a local folder

fsmap . --depth 2 --show-size --show-date

🌐 Scan a remote GitHub repo

fsmap --repo user/repo

💾 Export as markdown

fsmap . -o markdown > structure.md

📝 Save output to a file

fsmap . --output-format json --output-file structure.json

📑 Example Output (Text)

fsmap . --depth 1 --show-size --show-date

fsmap
└── dist (4.2 KB) [2025-05-23]
└── package.json (894 B) [2025-05-23]
└── src (7 files)

🔧 Available Options

| Option | Description | |---------------------------|-----------------------------------------------------------| | -d, --depth <n> | Limit recursion depth | | -e, --exclude <names> | Comma-separated list of folders/files to exclude | | --show-size | Display file sizes | | --show-date | Display last modified date | | --show-hidden | Include hidden files and folders | | --show-git | Display Git status (modified, untracked, ignored) | | -o, --output-format | Output format: text (default), markdown, json | | --output-file <path> | Save the output to a file instead of printing to console | | --repo <user/repo> | Clone and scan a GitHub repository | | --dry-run | Show scan result without writing anything | | -v, --version | Show version info | | -h, --help | Show help info |

🧠 Repo Caching Behavior

• ✅ If you scan the same repo again → uses cached clone
• 🔁 If you scan a different repo → deletes old repo, clones fresh
• 💡 Only one repo is ever cached at a time for performance and clarity

⚙️ Config

Add a fsmap.config.json file in your project root to override the default options.

Example:

{
    "$schema": "https://raw.githubusercontent.com/SwasthK/fsmap/main/fsmap.schema.config.json",
    "exclude": [
        "node_modules",
        ".git",
        "dist"
    ]
}

_NOTE: Cli written options override the config rules.

🛠 Plugin Support

Add a fsmap.config.ts file in your project root to transform or extend the file tree output.

Example:

module.exports = {
    transform(entry: FsMapEntry) {
        if (entry.name.endsWith("git.ts")) {
            entry.name = "🧪 " + entry.name;
        }
        return entry;
    }
}

🤝 Contributing

Found a bug? Have a feature idea? PRs are welcome — open an issue first!

📄 License

MIT

✨ Author

Made with ❤️ by Swasthik