file-organize

A powerful CLI tool for automatically categorizing and organizing files in directories based on their extensions.

Features
Installation
Usage
- Options
- Examples
Configuration
Getting Started with Development
- Prerequisites
- Setup
Running Tests
Contributing
Releasing
License

Features

🗃️ Automatically categorize files based on their extensions into organized folders
🔄 Recursively process subdirectories
🚫 Exclude files or directories using regex patterns
📊 Dry run mode tree-based visualization to preview changes before applying them
🪄 Flat mode for organizing all files at the root level
🌲 Tree visualization of the post organized structure
⚙️ (In Progress) Customizable configuration through JSON files

Installation

There are several ways to install file-organize depending on your preference:

1. Binary Installation (Recommended)

Download the pre-built binary for your operating system from the Releases page.

Windows

Download the file-organize-win-x64.exe file
Rename it to file-organize.exe (optional)
Add it to a location in your PATH or run it directly

macOS

# Download the binary
curl -L -o file-organize "https://github.com/himanshuc3/file-organize/releases/latest/download/file-organize-macos-x64"

# Make it executable
chmod +x file-organize

# Move to a directory in your PATH
sudo mv file-organize /usr/local/bin/

Linux

# Download the binary
curl -L -o file-organize "https://github.com/himanshuc3/file-organize/releases/latest/download/file-organize-linux-x64"

# Make it executable
chmod +x file-organize

# Move to a directory in your PATH
sudo mv file-organize /usr/local/bin/

2. NPM Package Installation

Install globally to use as a command-line tool from anywhere:

# Using npm
npm install -g file-organize

# Or using yarn
yarn global add file-organize

# Or using pnpm
pnpm add -g file-organize

3. Build from Source

If you want the latest features or need to customize the build:

# Clone the repository
git clone https://github.com/yourusername/file-organize.git
cd file-organize

# Install dependencies
npm install

# Build the project
npm run build

# Create binaries (optional)
npm run pkg

# The binaries will be available in the 'dist' directory

Usage

file-organize [options]

Options

Option	Alias	Description	Type	Default
`-d`	`--directory`	Directory to organize	string	Current directory (`.`)
`-r`	`--recursive`	Recursively organize each subdirectory	boolean	`false`
`-e`	`--exclude`	Exclude files and directories using regex	string	none
`-c`	`--config`	Path to config file for mapping folders to extensions (not being consumed currently)	string	none
`-f`	`--flat`	Flat map all files to root directory (Use with recursive flag to convert a tree structure to flat directory tree)	boolean	`false`
`-o`	`--dryRun`	Output the final file tree before organizing (no changes made)	boolean	`false`
`-h`	`--help`	Show help

Examples

Basic usage to organize a directory:

# To organize current files in current directory without recursive iteration
file-organize

# To organize files in a specfic directory relative to the cwd
file-organize -d path/to/directory

Recursively organize a directory and all subdirectories:

file-organize -d path/to/directory -r

Perform a dry run to preview changes without making them:

file-organize -o

Exclude files or directories matching a pattern:

file-organize -e "node_modules|\.git"

Default Configuration

The directories will categorize files according to the default configuration following the format given below. The option for customization will be supported soon via JSON files that can be saved and cached in system settings:

{
	"default": [
		{
			"name": "audio",
			"extensions": ["mp3", "wav", "aac", "wma"]
		},
		{
			"name": "video",
			"extensions": ["mp4", "mov", "avi", "mkv", "flv", "wmv"]
		},
		{
			"name": "documents",
			"extensions": [
				"zip",
				"doc",
				"docx",
				"ppt",
				"xls",
				"html",
				"txt",
				"pdf"
			]
		},
		{
			"name": "executables",
			"extensions": [
				"exe",
				"msi",
				"dmg",
				"pkg",
				"deb",
				"rpm",
				"app",
				"appx",
				"appxbundle",
				"appxupload"
			]
		},
		{
			"name": "images",
			"extensions": [
				"jpg",
				"jpeg",
				"png",
				"svg",
				"gif",
				"ico",
				"webp",
				"heic",
				"heif"
			]
		}
	],
	"prefix": "categorize",
	"extra": {
		"name": "miscellaneous"
	}
}

prefix: The prefix to be added to category folder names
default: Array of category objects, each with a name and array of extensions
extra: Configuration for uncategorized files

Getting Started with Development

Prerequisites

Node.js 16.0.0 or higher
npm, yarn, or pnpm (pnpm is recommended)

Setup

Clone the repository:

git clone https://github.com/yourusername/file-organize.git
cd file-organize

Install dependencies:

npm install

Build the project:

npm run build

Running Tests

To run the test suite:

npm run test

Contributing

Contributions are welcome! There's a list of features/enhancements for the next version of the tool present in Requirements.md that are up for grabs. Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Please make sure your code follows the existing style and passes all tests.

Releasing

To create a new release with automated binary builds:

Make sure all your changes are committed and merged to the main branch
Create and push a new tag with a version number:
```
git tag v1.0.0
git push origin v1.0.0
```
The GitHub Actions workflow will automatically:
- Build the project
- Create binaries for Windows, macOS, and Linux
- Publish a new GitHub Release with the binaries
- Publish the package to NPM

Note: You need to have the NPM_TOKEN secret configured in your GitHub repository settings for the NPM publishing step to work.

License

This project is licensed under the MIT License - see the LICENSE file for details.

himanshuc3/file-organize