autosort/README.md

A modern CLI tool to organize files in a directory.

# AutoSort

**AutoSort** is a powerful and intuitive command-line tool to organize files in a folder. Designed to be simple yet elegant, it provides flexible sorting options for files by name, extension, or creation date. With support for recursive folder sorting and real-time monitoring, AutoSort is the perfect tool to keep your files organized.

---

## Features

- **Sort by File Type (Extension)** (Default): Organize files based on their extensions.
- **Sort by Name**: Organize files alphabetically by their first letter.
- **Sort by Creation Date**: Group files based on their creation date.
- **Recursive Sorting**: Sort files in all subdirectories with the `--sub` option.
- **Active Mode**: Watch a folder for changes and sort files automatically with the `--active` option.
- **Dry Run**: Simulate the sorting process to see what would happen without making changes.
- **Logging**: Keep a detailed log of all actions performed.
- **Color-Coded Outputs**: Intuitive and colorful output for clear feedback.
- **Cross-Platform**: Works on Windows, macOS, and Linux.

---

## Installation

### Install via npm:

1. Add through NPM:
   ```bash
   npm install autosort
   ```

2. Run using default settings:
   ```bash
   autosort .
   ```

---

## Usage

Run `autosort` followed by the folder you want to organize.

```bash
autosort /path/to/folder [options]
```

### Options

| Option         | Alias | Description                                             |
|----------------|-------|---------------------------------------------------------|
| `--name`       | `-n`  | Sort files by their first letter.                       |
| `--extension`  | `-e`  | Sort files by their file type (extension).              |
| `--date`       | `-d`  | Sort files by their creation date.                      |
| `--sub`        | `-s`  | Sort files in all subdirectories recursively.           |
| `--active`     | `-a`  | Watch the folder for changes and sort files automatically. |
| `--dry`        |       | Simulate sorting without making changes.                |
| `--log`        | `-l`  | Generate a log file of actions taken.                   |
| `--help`       | `-h`  | Show help.                                              |

---

### Examples

#### Sort files by extension (default)
```bash
autosort /path/to/folder
```

#### Sort files by name
```bash
autosort /path/to/folder --name
```

#### Sort files by creation date recursively
```bash
autosort /path/to/folder --date --sub
```

#### Test sorting (dry run)
```bash
autosort /path/to/folder --extension --dry
```

#### Watch folder for changes and sort automatically
```bash
autosort /path/to/folder --active
```

#### Generate a log file
```bash
autosort /path/to/folder --log
```

---

## Logging

If the `--log` option is used, AutoSort generates a log file in the folder being sorted. The file is named based on the current timestamp. For dry runs, the log file includes `[TEST]` entries.

Example log file:
```
Test Run Log - 2025-01-04 15:00:00

[TEST] Would move: /path/to/folder/file1.txt → /path/to/folder/TXT/file1.txt
[TEST] Would move: /path/to/folder/file2.jpg → /path/to/folder/JPG/file2.jpg
```

---

## Developer Guide

### Setting Up the Project

Clone the repository:
```bash
git clone https://github.com/smirki/autosort.git
cd autosort
```

Install dependencies:
```bash
npm install
```

### Testing the Script Locally

Link the script to npm for testing:
```bash
npm link
```

You can now use the `autosort` command globally:
```bash
autosort /path/to/folder --name
```
---

### File Structure

```
autosort/
├── autosort.js          # Main script file
├── package.json         # Project configuration
├── README.md            # Documentation
├── .gitignore           # Ignored files
├── node_modules/        # Installed dependencies
```

---

## Contributing

We welcome contributions! To contribute:

1. Fork the repository.
2. Create a new branch for your feature/fix.
3. Commit your changes.
4. Submit a pull request.

---

## License

This project is licensed under the MIT License. See the `LICENSE` file for details.

---

## Contact

For support or inquiries, feel free to contact:

**Manav Majumdar**  
**GitHub:** [smirki](https://github.com/smirki)

---