GoPix

README

GoPix

A high-performance, feature-rich image conversion CLI tool built in Go.
Fast. Smart. Efficient. All from the terminal.

About • Features • Installation • Configuration • Technologies • Contributing • License

---

About

Welcome to GoPix — a blazing-fast image conversion CLI tool built with Go. GoPix empowers developers, designers, and power users with efficient batch image conversions, intelligent file handling, and performance-oriented architecture. Whether you’re processing thousands of photos or optimizing a single folder, GoPix handles it with speed and precision.

---

Features

🌟 Core Functionality

• Multi-format support: PNG, JPG, WebP, JPEG
• Parallel processing: Uses all CPU cores for maximum speed
• Real-time progress bar with ETA
• Smart resume for interrupted conversions
• Custom quality and compression settings

🛠️ Advanced Capabilities

• Enhanced Batch Processing: Process folders and subfolders with advanced options
  • Recursive directory traversal with depth control
  • Preserve or flatten directory structure
  • Custom output directory support
  • Group results by source folder
  • Skip empty directories
  • Follow symbolic links (optional)
• Size and resolution limits
• Configuration profiles with YAML support
• Dry-run mode to preview changes
• Backup of originals
• Rate limiting to prevent system overload
• Detailed post-process stats and reporting

🛡️ Security & Reliability

• Path validation to prevent directory traversal
• Safe defaults and permission checking
• Disk space validation before starting jobs
• Robust error handling and auto-retry mechanism

---

Installation

📦 Easy Install (Linux / Windows)

[!IMPORTANT] sudo is required for some installation commands on linux. GoPix Only supports x86_64 architecture. macOS will not be supported in the future.

Download the latest pre-built binary for your platform from the Releases page.

🐧 Linux

Extract the archive

tar -xzf gopix-linux-amd64.vX.Y.Z.tar.gz

Move the binary to the local bin directory

sudo mv linux/amd64/gopix /usr/local/bin

If you want to install for a specific user

mv linux/amd64/gopix /home/$USER/.local/bin

Then you can test the tool by running:

gopix -v

---

🪟 Windows

1. Download gopix-windows-amd64-vX.Y.Z.zip from the Releases page.

2. Extract the archive to a folder of your choice.

3. Move the binary located at windows/amd64/gopix.exe to any folder of your choice or C:\Program Files\GoPix\bin.

4. Add that folder to your System PATH:

   • Open System Properties → Environment Variables → Path → Edit → Add new.

Then you can test the tool by running:

gopix -v

---

🏗️ Build from Source (Linux, Windows)

![📝 Note] GoPix uses a Makefile to build and install the CLI tool. Make sure you have the make utility Go and git installed on your system. The script may adjust environment-specific paths depending on your OS.

---

🔧 Step 1: Install make (if not already installed)

For Arch Linux and based distros:

sudo pacman -S base-devel mingw-w64-gcc

For Debian / Ubuntu and based distros:

sudo apt install build-essential gcc-mingw-w64-x86-64

For Fedora and based distros:

sudo dnf install make mingw64-gcc

For openSUSE and based distros:

sudo zypper install make mingw64-gcc

For Windows:

• Option 1: Install MSYS2 [recommended]
• Option 2: Use Git Bash and run the following command:

  pacman -Syu
  pacman -S make
  

---

⚙️ Step 2: Clone and Build

git clone --depth 1 https://github.com/MostafaSensei106/GoPix.git
cd GoPix
make

---

✅ Result

• This will compile GoPix from source optmized for your os and cpu architecture and install it locally.
• The binary will be placed in your system's executable path (like /usr/local/bin on Linux/macOS).
• You can now run:

gopix help

---

🆙 Upgrading

[!Note] To upgrade GoPix, make sure you have the required development tools installed: go, make, and git.

To upgrade GoPix to the latest version, simply run

gopix upgrade

This will:

• Clone or update the latest source from GitHub.
• Rebuild the binary using your current platform and architecture.
• Replace the old version automatically.

OR

get the latest pre-built binary for your platform from Releases page and follow Installation Instructions.

---

🚀 Quick Start

# Convert all images in a directory to PNG
gopix -p ./images -t png

# Convert to JPEG with 90% quality and keep originals
gopix -p ./images -t jpg -q 90 --keep

# Preview changes without applying them
gopix -p ./images -t webp --dry-run

---

📋 Usage Examples

🔁 Basic Conversion

gopix -p ./photos -t webp -q 95

💾 With Backup

gopix -p ./photos -t png --backup

⚙️ Advanced Usage

gopix -p ./photos -t jpg -w 8 --rate-limit 5
gopix -p ./photos -t png -v --log-file

🔄 Batch Processing Examples

# Process all images recursively with structure preservation
gopix -p ./photos -t webp --recursive --preserve-structure

# Process with custom output directory
gopix -p ./photos -t png --output-dir ./converted --recursive

# Process with depth limit (only 2 levels deep)
gopix -p ./photos -t jpg --recursive --max-depth 2

# Process without preserving structure (flatten all files)
gopix -p ./photos -t webp --recursive --no-preserve-structure

# Process with grouping by folder
gopix -p ./photos -t png --recursive --group-by-folder

# Process following symbolic links
gopix -p ./photos -t jpg --recursive --follow-symlinks

---

Configuration

GoPix uses a YAML config file located at:

# on Linux
~/Home/$USER/.gopix/config.yaml

🧾 Example Config:

default_format: "png"
quality: 85
workers: 8
max_dimension: 4096
log_level: "info"
auto_backup: false
resume_enabled: true
# supported_extensions: ["jpg", "jpeg", "png", "webp"] # Do not add any formats here,

# Batch processing configuration
batch_processing:
  recursive_search: true
  max_depth: 0  # 0 = unlimited depth
  preserve_structure: true
  output_dir: ""  # Custom output directory (empty = use input directory)
  group_by_folder: false
  skip_empty_dirs: true
  follow_symlinks: false

All settings can be overridden using CLI flags.

---

Technologies

Technology	Description
🧠 Golang	go.dev — The core language powering GoPix: fast and efficient
🛠️ Cobra (CLI)	spf13/cobra — CLI commands, flags, and UX
🎨 Fatih/color	fatih/color — Terminal text styling and coloring
🔄 WebP encoder	chai2010/webp — Image conversion to/from WebP
📏 Resize	nfnt/resize — Image resizing utilities
📉 Progress bar	schollz/progressbar — Beautiful terminal progress bar
📦 YAML config	gopkg.in/yaml.v3 — Config file parser
📜 Logrus	sirupsen/logrus — Advanced logging framework

---

Contributing

Contributions are welcome! Here’s how to get started:

1. Fork the repository
2. Create a new branch: git checkout -b feature/YourFeature
3. Commit your changes: git commit -m "Add amazing feature"
4. Push to your branch: git push origin feature/YourFeature
5. Open a pull request

💡 Please open an issue first for major feature ideas or changes.

---

License

This project is licensed under the GPL-3.0 License. See the LICENSE file for full details.

Made with ❤️ by MostafaSensei106

---