file-organize

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

Table of Contents

• Features
• Installation
  • Binary Installation
  • NPM Package Installation
  • Build from Source
• 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

1. Clone the repository:

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

2. Install dependencies:

npm install

3. 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.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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:

1. Make sure all your changes are committed and merged to the main branch
2. Create and push a new tag with a version number:

   git tag v1.0.0
   git push origin v1.0.0

3. 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.