Branch-Flow CLI Tool

branch-flow is a python CLI tool to visualize directory structures as a tree with customizable features

Features

Option	Long Option	Description
-d	--max-depth	Limit how deep the directory tree goes
-i	--ignore	Ignore specific files or folders
-s	--show-size	Show file sizes next to file names
-k	--kb	Display sizes in kilobytes instead of bytes
-n	--no-color	Disable colored output (useful for plain terminals)
-x	--no-icons	Disable file/folder icons
	--force-icons	Force icons to show even in exports
-f	--filter-ext	Show only files with these extensions (e.g., .py, .md)
-o	--output	Write the output to a text file
-j	--json	Write output as nested JSON

There is also a nice summary at the end of the terminal output which is attached to the exported .txt file and also in the exported json file

Output Customizations

• Colors:

  • Folders = Blue
  • Files = Green
  • Can be disabled with --no-color

• Icons:

  • Folder = 📁
  • File = 📄
  • Can also be disabled with --no-icons
  • Disabled automatically in exports unless --force-icons is used

• Size Format:

  • Use --show-size to display sizes
  • Add --kb to show sizes in kilobytes

Export Options

• --output FILE.txt: Save tree structure as plain text
• --json FILE.json: Save tree structure in nested JSON
  • JSON format uses a recursive structure with children for directories

Example Usage

Note: This script may be published on PyPI in the future. Until then, you can use it by downloading directly or making it globally accessible via your $PATH.

Option 1: Run from the Script Directory

python3 branch_flow.py your-directory -i .git node_modules -d 2 -s -k -x -f .py .md -o tree.txt -j tree.json -n --force-icons

Option 2: Add Script to $PATH for Global Access

1. Make your script executable:

   chmod +x branch_flow.py

2. Add a shebang line at the top of the file:

   #!/usr/bin/env python3

3. Move the script to a directory in your $PATH:

   sudo mv branch_flow.py /usr/local/bin/branch-flow

4. Now you can run it from anywhere:

   branch-flow your-directory -i .git node_modules -d 2 -s -k -x -f .py .md -o tree.txt -j tree.json -n --force-icons