diff --git a/README.md b/README.md index f3964cc..e1057b5 100644 --- a/README.md +++ b/README.md @@ -1,61 +1,202 @@ -# ⚡ treels -Treels, a CLI tool built in Go, merges the tree and ls commands while introducing intuitive merging and beautification features, -simplifying directory navigation and enhancing the command-line experience. +# treels -> [!IMPORTANT] -> To ensure that icons are displayed correctly in the terminal, it's recommended to use Nerd fonts. For example, you can download the FiraCode Nerd Font from [here](https://github.com/ryanoasis/nerd-fonts/releases/). +`treels` is a small Go CLI that blends the quick scan of `ls` with the structure of `tree`. +Use it to inspect a directory as a compact grid, expand it as a tree, hide project noise with +`.gitignore`, and keep large repositories readable with depth limits. -## 🚀 Installation +```bash +treels # compact ls-style view +treels -t # tree view +treels -t --depth 2 # tree view, limited to two levels +treels -t --gitignore # tree view, excluding .gitignore matches +``` -To install the `treels` command-line tool, ensure you have Go 1.25.0 or newer installed on your system. If not, you can download and install it from the [official Go website](https://golang.org/dl/). +> [!NOTE] +> File and folder icons look best with a Nerd Font installed. If your terminal does not support +> Nerd Font glyphs, use `--no-icons`. + +## Preview + +Compact directory listing: + +```text +$ treels --no-icons file-icons-example +. +Dockerfile Main.kt Program.cs +app.conf app.lock app.log +app.rb app.swift backup.zip +c-file.c class-java-file.class component.vue +config.xml cpp-file.cpp document.pdf +index.html index.php java-file.java +javascript-file.js json-file.json logo.png +main.tf package.json plb-file.plb +pls-file.pls python-file.py react-component.jsx +react-typescript.tsx rust-file.rs script.sh +song.mp3 sql-file.sql styles.css +typescript-file.ts video.mp4 yaml-file.yml + +0 directories, 36 files +``` -Once you have Go installed, open a terminal or command prompt and run the following command: +Tree view with a depth limit: + +```text +$ treels -t --depth 1 --gitignore --no-icons +. +├── LICENSE +├── README.md +├── cmd +├── example +├── file-icons-example +├── go.mod +├── go.sum +├── main.go +├── module +├── service +└── utils + +6 directories, 5 files +``` + +Focused tree view for one directory: + +```text +$ treels -t --depth 2 --no-icons service +. +├── gitignore.go +├── service.go +├── service_test.go +└── util.go + +0 directories, 4 files +``` + +## Features + +- Compact grid output for fast directory scans. +- Recursive tree output with familiar branch characters. +- Optional Nerd Font icons and file-type colors. +- `--gitignore` support to skip generated files, dependencies, logs, and build output. +- `--depth N` to keep tree output readable in large repositories. +- `--readable` file sizes. +- `--all` support for hidden files. +- `--no-icons` fallback for terminals without icon fonts. + +## Installation + +Install with Go: ```bash go install github.com/oussamaM1/treels@latest ``` -This command will download the repository, build the `treels` executable, and place it in your Go binary directory. Make sure your Go binary directory is in your system's PATH so that you can execute `treels` from any directory. +Make sure your Go binary directory is in your `PATH`. You can check where Go installs binaries with: + +```bash +go env GOPATH +``` + +The binary is usually placed in: + +```text +$(go env GOPATH)/bin +``` + +## Usage + +```bash +treels [flags] [path] +``` + +If no path is provided, `treels` lists the current directory. + +## Examples + +List the current directory: + +```bash +treels +``` + +Include hidden files: + +```bash +treels --all +``` + +Show a tree: + +```bash +treels --tree +``` + +Limit tree depth: + +```bash +treels --tree --depth 2 +``` -## ⚡ Usage +Respect `.gitignore` rules: ```bash -treels [Flags] [Path] +treels --tree --gitignore ``` -## 🏷️ Flags +Show readable sizes: -- `-a, --all`: List all files and directories -- `-h, --help`: Help for treels -- `-t, --tree`: Tree view of the directory -- `--no-icons`: Disable icons -- `--gitignore`: Respect .gitignore rules -- `--depth N`: Limit tree view recursion depth -- `-r, --readable`: Show human-readable size for each file and directory -- `-v, --version`: Show treels version +```bash +treels --readable +``` -## 📋 Example +Disable icons: ```bash -treels -a +treels --no-icons ``` -This command will list all files and directories in the `current` directory. +## Flags + +| Flag | Description | +| --- | --- | +| `-a`, `--all` | List hidden files and directories. | +| `-t`, `--tree` | Show recursive tree view. | +| `--depth N` | Limit tree recursion depth. | +| `--gitignore` | Respect `.gitignore` rules from the target directory. | +| `--no-icons` | Disable file and folder icons. | +| `-r`, `--readable` | Show human-readable file and directory sizes. | +| `-v`, `--version` | Print the current version. | +| `-h`, `--help` | Show help. | + +## Fonts + +Icons require a Nerd Font-compatible terminal. Recommended setup: + +1. Install a Nerd Font, such as FiraCode Nerd Font. +2. Select that font in your terminal profile. +3. Run `treels` normally. -![](example/example-treels-a.png) +If icons render as empty boxes or odd symbols, use: ```bash -treels -t /Project/treels +treels --no-icons ``` -This command will display the tree view of the `/Project/treels/` directory. +## Development -![](example/example-treels-t.png) +Run tests: ```bash -treels -t --no-icons /Project/treels +go test ./... ``` -This command will display the tree view without icons of the `/Project/treels/` directory. +Run lint: -![](example/example-treels-it.png) +```bash +golangci-lint run +``` + +Build locally: + +```bash +go build . +```