🗂️ 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