You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+55-55Lines changed: 55 additions & 55 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,7 @@
6
6
7
7
# TraceView
8
8
9
-
🚀 **TraceView** is a fast and feature-rich TUI (Text-based User Interface) application written in Rust. It enables users to navigate the local filesystem, monitor system resources, search for files and directories, retrieve metadata, and export search results to JSON. The app is configurable via a `config.toml` file and provides a smooth user experience with different themes.
9
+
A fast and feature-rich TUI (Text-based User Interface) application written in Rust. It enables users to navigate the local filesystem, monitor system resources, search for files and directories, retrieve metadata, and export search results to JSON. The app is configurable via a `config.toml` file and provides a smooth user experience with different themes.
10
10
11
11
---
12
12
@@ -15,15 +15,15 @@
15
15
---
16
16
17
17
## 🧩 Features
18
-
-📂 **Filesystem Explorer**: Quickly browse and navigate local directories.
19
-
-📊 **System Overview**: Monitor CPU, Swap, memory, and disk usage in real-time.
20
-
-🔎 **File & Directory Search**: Search files and folders by name with instant results.
21
-
-🗂️ **Metadata Retrieval**: View file and directory metadata (size, permissions, last modified, and more).
22
-
-📝 **Export Functionality**: Save search results as JSON files.
23
-
-⚙️ **Configurable Settings**: Customize behavior and appearance via `config.toml`.
24
-
-🎨 **Themes**: Choose from **Dark**, **Light**, **Dracula**, and **Indigo** themes.
25
-
-❓ **Help Page**: Built-in help page with keybindings and usage instructions.
26
-
-📊 **Status Bar**: Displays current context, active theme, last keystroke, and error messages in real-time.
18
+
-**Filesystem Explorer**: Quickly browse and navigate local directories.
19
+
-**System Overview**: Monitor CPU, Swap, memory, and disk usage in real-time.
20
+
-**File & Directory Search**: Search files and folders by name with instant results.
21
+
-**Metadata Retrieval**: View file and directory metadata (size, permissions, last modified, and more).
22
+
-**Export Functionality**: Save search results as JSON files.
23
+
-**Configurable Settings**: Customize behavior and appearance via `config.toml`.
24
+
-**Themes**: Choose from **Dark**, **Light**, **Dracula**, and **Indigo** themes.
25
+
-**Help Page**: Built-in help page with keybindings and usage instructions.
26
+
-**Status Bar**: Displays current context, active theme, last keystroke, and error messages in real-time.
27
27
28
28
---
29
29
@@ -33,7 +33,7 @@
33
33
### 📦 Installation
34
34
There are three ways to get started with TraceView:
35
35
36
-
#### 🏗️ **Option 1: Build from Source**
36
+
#### Option 1: Build from Source
37
37
1.**Clone the repository**:
38
38
```bash
39
39
git clone https://github.com/javaLux/traceview
@@ -49,10 +49,10 @@ There are three ways to get started with TraceView:
49
49
./traceview
50
50
```
51
51
52
-
#### 📥 **Option 2: Download Pre-Compiled Binaries***(Recommended for quick setup)*
52
+
#### Option 2: Download Pre-Compiled Binaries *(Recommended for quick setup)*
53
53
If you don't want to build the project yourself or don't want to install Rust, you can download pre-compiled binaries from the [Releases](https://github.com/javaLux/traceview/releases) section on GitHub:
54
54
55
-
##### 🔑 **How to Run the Downloaded Binary:**
55
+
##### **How to Run the Downloaded Binary:**
56
56
1. Download the appropriate file for your operating system.
57
57
2. Extract the archive if necessary.
58
58
3. Make the binary executable (Linux/macOS):
@@ -64,7 +64,7 @@ If you don't want to build the project yourself or don't want to install Rust, y
64
64
./traceview
65
65
```
66
66
67
-
#### 📦 **Option 3: Install via crates.io***(Quick and direct installation)*
67
+
#### Option 3: Install via crates.io *(Quick and direct installation)*
68
68
TraceView is available on [crates.io](https://crates.io/crates/traceview), allowing users to install and run it directly without cloning the repository.
69
69
70
70
1.**Install using Cargo:**
@@ -77,7 +77,7 @@ TraceView is available on [crates.io](https://crates.io/crates/traceview), allow
77
77
traceview
78
78
```
79
79
80
-
✅ **Advantages of this method:**
80
+
**Advantages of this method:**
81
81
- The installed binary is placed in Cargo's bin directory (usually `~/.cargo/bin`), which is typically included in the system's `$PATH` environment variable.
82
82
- You can run `traceview` directly from any terminal without specifying the path.
83
83
- Easily update to the latest version with:
@@ -88,7 +88,7 @@ TraceView is available on [crates.io](https://crates.io/crates/traceview), allow
88
88
89
89
<br>
90
90
91
-
## 🎨 Configuration
91
+
## ⚙️ Configuration
92
92
TraceView is configurable via the `config.toml` file located in the Config-Directory. Below is the structure of the default configuration file:
93
93
94
94
```toml
@@ -99,7 +99,7 @@ follow_sym_links = false
99
99
```
100
100
* You can see the applied configurations at any time in the app by pressing `F2`.
101
101
102
-
### ⚙️ **Configuration Options**
102
+
### Configuration Options
103
103
-**theme**: Describes the default theme on startup. Accepted values: "Dark", "Light", "Dracula", "Indigo".
104
104
-**Default:** "Dark"
105
105
-**start_dir**: Describes the directory in which the file explorer should start. Leave empty to start in the current working directory.
@@ -110,13 +110,13 @@ follow_sym_links = false
110
110
-**What are symbolic links?** Symbolic links (or symlinks) are pointers to other files or directories. When this option is set to `true`, TraceView follows these links during navigation and searches, potentially traversing linked paths. When set to `false`, symlinks are ignored to avoid accidental infinite loops or unintended directory traversals.
111
111
-**Default:** false
112
112
113
-
### ⚠️ **Invalid Configuration Handling**
113
+
### ⚠️ Invalid Configuration Handling
114
114
If any settings in `config.toml` are incorrect or cannot be interpreted:
115
115
- The application will log a warning in the **log file** located in the app's `data` directory.
116
116
- Default settings will be applied automatically to ensure stability.
117
117
- Users should consult the log file for details on which settings failed to load and why.
118
118
119
-
### 🖥️ **Command-Line Interface (CLI) Options**
119
+
### Command-Line Interface (CLI) Options
120
120
In addition to the `config.toml` file, TraceView supports command-line options for quick configuration overrides:
121
121
122
122
| Option | Description | Default | Constraints |
@@ -125,7 +125,7 @@ In addition to the `config.toml` file, TraceView supports command-line options f
-🖤 **Dark** – High contrast for low-light environments (default)
144
-
-🤍 **Light** – Bright theme for well-lit spaces
145
-
-🧛 **Dracula** – Vibrant dark theme with colorful highlights
146
-
-🟣 **Indigo** – Calming theme with indigo tones
143
+
-**Dark** – High contrast for low-light environments (default)
144
+
-**Light** – Bright theme for well-lit spaces
145
+
-**Dracula** – Vibrant dark theme with colorful highlights
146
+
-**Indigo** – Calming theme with indigo tones
147
147
148
148
To change the theme you can press `Tab` within the app or if you want to set a default theme on startup, update the `theme` value in `config.toml` file.
149
149
@@ -154,18 +154,18 @@ To change the theme you can press `Tab` within the app or if you want to set a d
154
154
## App Contexts
155
155
TraceView operates in three primary contexts, each with context-specific controls and keybindings:
156
156
157
-
1.**Explorer Context**🗂️ – Navigate and browse the filesystem.
158
-
2.**Search Context**🔎 – Input and execute file/directory searches.
159
-
3.**Result Context**📄 – View and export search results.
157
+
1.**Explorer Context** – Navigate and browse the filesystem.
158
+
2.**Search Context** – Input and execute file/directory searches.
159
+
3.**Result Context** – View and export search results.
160
160
161
161
* Please use the provided help page by pressing `F1` to view all keyboard shortcuts and their context.
162
162
163
163
## 🧮 Status Bar Features
164
164
The status bar, located at the bottom of the interface, provides:
165
-
-🗂️ **Current Context**: Shows whether you are in Explorer, Search, or Result context.
166
-
-🎨 **Active Theme**: Displays the currently applied theme.
167
-
-⌨️ **Last Keystroke**: Shows the last pressed key.
168
-
-❗ **Error Messages**: Displays any application errors or warnings.
165
+
-**Current Context**: Shows whether you are in Explorer, Search, or Result context.
166
+
-**Active Theme**: Displays the currently applied theme.
167
+
-**Last Keystroke**: Shows the last pressed key.
168
+
-**Error Messages**: Displays any application errors or warnings.
169
169
---
170
170
171
171
<br>
@@ -176,17 +176,17 @@ TraceView provides a powerful search feature that allows users to search specifi
176
176
- Search by partial matches (e.g., typing "log" to find "app_log.txt").
177
177
- Search by file extensions (e.g., ".txt" to find all text files).
178
178
179
-
### 🔍 **Search Options:**
179
+
### Search Options
180
180
TraceView offers two search modes:
181
181
-**Flat Search:** 🔎 Searches only within the currently selected directory (non-recursive). Ideal for quick local searches.
182
182
-**Deep Search:** 🌐 Recursively searches through all subdirectories within the selected path. Useful for locating files or directories in nested structures.
183
183
184
-
### 📝 **Search Input History:**
184
+
### Search Input History
185
185
- The input field for typing search queries maintains a **history of previous searches** during the current session.
186
186
- Navigate through past queries using the **Up (↑)** and **Down (↓)** arrow keys to quickly reuse or modify previous searches.
187
187
- This feature enhances efficiency, especially when refining searches or repeating common queries.
188
188
189
-
✅ **Usage Notes:**
189
+
**Usage Notes:**
190
190
- Initiate a search by pressing `Ctrl + F` in the Explorer Context.
191
191
- Enter your search query and choose between Flat or Deep mode.
192
192
- Search results are displayed instantly based on the selected mode.
@@ -199,13 +199,13 @@ TraceView offers two search modes:
199
199
<br>
200
200
201
201
## 🗂️ Capturing File and Directory Metadata
202
-
TraceView allows users to capture metadata for both files and directories with the following considerations:
202
+
TraceView allows users to capture metadata (press `Ctrl + A` in Explorer Context), for both files and directories with the following considerations:
203
203
204
-
### 📄 **File Metadata**
205
-
- File metadata is available immediately after invoking the metadata view (press `Ctrl + A` in Explorer Context).
204
+
### 📄 File Metadata
205
+
- File metadata is available immediately after invoking the metadata view.
206
206
- Displayed information includes file size, permissions, last modified date, and ownership.
207
207
208
-
### 📁 **Directory Metadata**
208
+
### 📁 Directory Metadata
209
209
- Directory metadata collection may take longer, especially for large directories.
210
210
- This is because TraceView recursively scans all contained files and subdirectories to determine:
211
211
- 📏 Total size
@@ -220,7 +220,7 @@ TraceView allows users to capture metadata for both files and directories with t
220
220
## ⏳ If Things Take a Long Time
221
221
Some operations in TraceView, such as searching for files/directories or exporting search results, may take longer to complete depending on the size and complexity of the filesystem.
222
222
223
-
✅ **Cancel Ongoing Processes:**
223
+
**Cancel Ongoing Processes:**
224
224
- You can quit the app at any time by pressing `Ctrl + Q`.
225
225
- This is especially useful during deep searches or large directory exports that require extensive processing time.
226
226
---
@@ -229,9 +229,9 @@ Some operations in TraceView, such as searching for files/directories or exporti
229
229
230
230
## 🚫 Limitations & Future Plans
231
231
While TraceView offers a variety of features for browsing, searching, and viewing metadata, it is important to note that **it is not a full-fledged file explorer**. As such:
232
-
-🗑️ **File or directory manipulation (copying, moving, deleting, or renaming) is not supported.**
233
-
-🚀 **These features may be planned for a future release** to enhance the app’s file management capabilities.
234
-
-📄 TraceView is currently designed to provide safe, read-only access to filesystem information without risking unintended file modifications.
232
+
-**File or directory manipulation (copying, moving, deleting, or renaming) is not supported.**
233
+
-**These features may be planned for a future release** to enhance the app’s file management capabilities.
234
+
- TraceView is currently designed to provide safe, read-only access to filesystem information without risking unintended file modifications.
235
235
---
236
236
237
237
<br>
@@ -245,9 +245,9 @@ This project is licensed under the MIT License.
245
245
246
246
## 🧰 Built With ❤️ in Rust and these awesome crates
247
247
Thanks to the developers of these crates, without whom `TraceView` would not exist<br>
248
-
-🖥️ **[Ratatui](https://crates.io/crates/ratatui)** – Rust-based library for building rich terminal user interfaces. 🖼️
249
-
-📁 **[Walkdir](https://crates.io/crates/walkdir)** – Efficient directory traversal for Rust projects. 🚶♂️
When testing under MacOs, I noticed that the standard terminal does not fully support true RGB (24-bit) colors. For this reason, the test was also carried out with the third-party terminal `iTerm2'`. There all colors are displayed as expected. So if you notice an incorrect display of colors under MacOs, please use the [iTerm2](https://iterm2.com/) terminal.
@@ -270,13 +270,13 @@ When testing under MacOs, I noticed that the standard terminal does not fully su
270
270
<br>
271
271
272
272
## 🛠️ Troubleshooting
273
-
### 🪟 **Windows Terminal Freeze Issue**
273
+
### Windows Terminal Freeze Issue
274
274
If you experience the app freezing when clicking inside the terminal window with the **left mouse button** on Windows, this is due to the terminal's default behavior of entering "selection mode." In this mode, terminal input is paused while text is being selected. To avoid this issue:
275
275
- Use keyboard navigation instead of mouse clicks.
276
276
- Right-click outside the terminal to regain control.
277
277
- Change terminal settings to disable selection mode if supported.
278
278
279
-
### ❗ **Error Messages and Logs**
279
+
### Error Messages and Logs
280
280
If an error appears in the status bar:
281
281
- A brief error description is displayed in the status bar.
282
282
- For detailed information, consult the **log file** located in the app's `data` directory.
@@ -290,20 +290,20 @@ If an error appears in the status bar:
290
290
## 🤝 **Collaboration, Feedback & Bug Reports**
291
291
I welcome feedback, suggestions, and bug reports! Your input helps make TraceView better.
292
292
293
-
### 💬 **How to Contribute:**
293
+
### How to Contribute
294
294
- Report issues or suggestions via [GitHub Issues](https://github.com/javaLux/traceview/issues).
295
295
- Submit pull requests to improve the code or documentation.
296
296
- Share your thoughts to help shape future features.
297
297
298
-
### 🐛 **Found a Bug?**
298
+
### Found a Bug?
299
299
- Check if it’s already reported.
300
300
- If new, open an issue with details and reproduction steps.
301
301
- Attach logs (in `data` directory) for faster diagnosis.
302
302
303
-
### 📢 **I Appreciate Your Feedback!**
303
+
### I Appreciate Your Feedback!
304
304
Your ideas and input make TraceView more user-friendly. Don’t hesitate to reach out.
0 commit comments