issue #70: Update readme docs

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 .
+```