Metadata-Version: 2.4
Name: crossrename
Version: 1.6.0
Summary: Harmonize file and directory names for Linux, Windows and macOS.
Keywords: files,folders,rename,linux,windows,macos,transferring,filename
Author: Emmanuel C. Jemeni
Author-email: Emmanuel C. Jemeni <jemenichinonso11@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Requires-Dist: packaging>=26.2
Requires-Python: >=3.12
Project-URL: Bug Tracker, https://github.com/Jemeni11/CrossRename/issues
Project-URL: Changelog, https://github.com/Jemeni11/CrossRename/blob/master/CHANGELOG.md
Project-URL: Funding, https://buymeacoffee.com/jemeni11
Project-URL: Homepage, https://github.com/Jemeni11/CrossRename
Description-Content-Type: text/x-rst

CrossRename
===========

.. image:: https://github.com/Jemeni11/CrossRename/blob/master/logo.png?raw=true
   :alt: CrossRename Logo
   :width: 128px
   :height: 128px
   :align: center


Harmonize file and directory names for Linux, Windows, and macOS.

`Explore the repo » <https://github.com/Jemeni11/CrossRename>`__


Table of Contents
-----------------

- `Introduction`_
- `Features`_
- `Installation`_
- `Usage`_

  - `Examples`_
  - `Unicode Alternatives Mode`_
  - `Safety First`_

- `Platform Compatibility`_
- `Why did I build this?`_
- `Contributing`_
- `Wait a minute, who are you?`_
- `License`_
- `Changelog`_

Introduction
------------

CrossRename is a command-line tool designed to harmonize file and directory names across Linux, Windows, and macOS systems.
It ensures that your file names are compatible with all three operating systems, eliminating naming conflicts
when transferring files between different environments.

Features
--------

- Sanitizes file names to be Windows-compatible (and thus Linux-compatible and macOS-compatible)
- Byte-aware filename truncation (correctly handles CJK, Cyrillic, emoji, and other multi-byte UTF-8 characters)
- Option to replace forbidden characters with Unicode lookalikes instead of removing them
- Optionally renames directories to be cross-platform compatible
- Handles both individual files and entire directories
- Supports recursive renaming of files in subdirectories
- Preserves file extensions, including compound extensions like .tar.gz
- Provides informative logging
- Provides a dry-run mode to preview renaming changes without executing them
- Interactive safety warnings with option to skip for automation
- Skips recursive symlinks to avoid infinite loops

`back to introduction  <introduction_>`__

Installation
------------

From PyPI (Using PIP)
~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   pip install CrossRename

`back to introduction  <introduction_>`__

Usage
-----

.. code-block:: text

   usage: crossrename [-h] [-p PATH] [-v] [-u] [-r] [-d] [-D] [-a] [--force] [-q] [--credits] [--max-filename-bytes N]

   Harmonize file and directory names for Linux, Windows and macOS.

   options:
     -h, --help                  show this help message and exit
     -p, --path PATH             The path to the file or directory to rename.
     -v, --version               Prints out the current version and quits.
     -u, --update                Check if a new version is available.
     -r, --recursive             Rename all files in the directory path given and its subdirectories. When used with -D, also renames subdirectories.
     -d, --dry-run               Perform a dry run, logging changes without renaming.
     -D, --rename-directories    Also rename directories to be cross-platform compatible. Use with caution!
     -a, --use-alternatives      Replace forbidden characters with Unicode lookalikes instead of removing them. May cause display issues on some systems.
     --force                     Skip safety prompts (useful for automated scripts)
     -q, --quiet                 Suppress 'No change needed' and other informational messages. Only shows files that are actually renamed, plus warnings and errors.
     --credits                   Show credits and support information
     --max-filename-bytes N      Maximum filename length in bytes (default: 255, valid range: 16-255). Filenames exceeding this limit will be truncated. The default of 255 bytes ensures compatibility with Linux filesystems (ext4, btrfs). Multi-byte characters (CJK, Cyrillic, emoji) consume more bytes per character.

   Made with <3 by Emmanuel Jemeni | Send Feedback: https://tally.so/r/7Rjpgz?project=CrossRename

`back to introduction  <introduction_>`__

Examples
~~~~~~~~

Rename a single file:

.. code-block:: bash

   crossrename -p /path/to/file.txt

Rename all files in a directory (and its subdirectories):

.. code-block:: bash

   crossrename -p /path/to/directory -r

Rename all files AND directories recursively:

.. code-block:: bash

   crossrename -p /path/to/directory -r -D

Rename a single directory:

.. code-block:: bash

   crossrename -p /path/to/problematic_directory -D

Perform a dry run to preview renaming changes without executing them:

.. code-block:: bash

   crossrename -p /path/to/directory -r -D -d

Skip safety prompts for automated scripts:

.. code-block:: bash

   crossrename -p /path/to/directory -r -D --force

Use Unicode alternatives instead of removing characters:

.. code-block:: bash

   crossrename -p /path/to/file.txt -a

Check for an update:

.. code-block:: bash

   crossrename -u

Show credits and project information:

.. code-block:: bash

   crossrename --credits

Limit filename length for Linux filesystems (useful for CJK or emoji-heavy filenames):

.. code-block:: bash

   crossrename -p /path/to/directory -r --max-filename-bytes 255

Suppress informational messages to see only files that will be renamed:

.. code-block:: bash

   crossrename -p /path/to/directory -r -d -q
   # Only shows [Dry-run] Would rename: ... lines and skips "No change needed" noise

`back to introduction  <introduction_>`__


Unicode Alternatives Mode
~~~~~~~~~~~~~~~~~~~~~~~~~

Use `--use-alternatives` to replace forbidden characters with similar Unicode characters instead of removing them:


.. code-block:: bash

   crossrename -p "file<name>.txt" --use-alternatives
    # Result: "fileᐸnameᐳ.txt" instead of "filename.txt"

Character mappings:

- ``<`` → ``ᐸ`` (Canadian Syllabics Pa)
- ``>`` → ``ᐳ`` (Canadian Syllabics Po)
- ``:`` → ``∶`` (Ratio)
- ``"`` → ``ʺ`` (Modified Letter Double Prime)
- ``/`` → ``∕`` (Division Slash)
- ``\`` → ``⧵`` (Reverse Solidus Operator)
- ``|`` → ``∣`` (Divides)
- ``?`` → ``﹖`` (Small Question Mark)
- ``*`` → ``🞱`` (Bold Five Spoked Asterisk)

.. warning::
   These Unicode characters may not display correctly on all systems, fonts, or applications.

`back to introduction  <introduction_>`__

Safety First
~~~~~~~~~~~~

.. warning::
   Always run with ``--dry-run`` first!

CrossRename will show interactive safety warnings before making any changes to help prevent accidental data loss.
However, it's strongly recommended to:

1. **Run a dry run first** to preview what will be changed:

   .. code-block:: bash

      crossrename -p /your/path -r -D -d

2. **Backup your data** before running the tool on important files

3. **Use** ``--force`` **flag** for automation in CI/CD pipelines:

   .. code-block:: bash

      crossrename -p /your/path -r -D --force

Directory renaming is particularly powerful and potentially disruptive since it changes folder paths that other
applications might reference.

`back to introduction  <introduction_>`__

Platform Compatibility
----------------------

CrossRename works on:

- **Windows**
- **Linux**
- **macOS**

The tool sanitizes filenames to be compatible with the *most restrictive* filesystem (Windows),
ensuring files work everywhere. This means:

- Removing Windows-forbidden characters: ``< > : " / \ | ? *``
- Handling Windows reserved names: CON, PRN, AUX, NUL, COM1-9, LPT1-9
- Removing trailing spaces and periods
- Removing control characters
- Limiting filenames to 255 **bytes** (for ext4/btrfs compatibility; configurable via ``--max-filename-bytes``)

.. note::
   **Prior to v1.5.0**, CrossRename limited filenames to 255 **characters**, which could still produce
   filenames that fail on Linux. ext4 and btrfs enforce a 255 **byte** limit, not a character limit.
   Since non-ASCII characters in UTF-8 occupy more than one byte, the effective character limit is lower:

   .. list-table::
      :header-rows: 1

      * - Script
        - Bytes per char
        - Effective limit
      * - Latin (ASCII)
        - 1
        - ~255 characters
      * - Cyrillic
        - 2
        - ~127 characters
      * - CJK (Chinese, Japanese, Korean)
        - 3
        - ~85 characters
      * - Emoji
        - 4
        - ~63 characters

   v1.5.0 fixes this with byte-aware truncation. If you have files that were previously
   "within the limit" but still fail to copy to a Linux filesystem, re-run CrossRename to truncate them correctly.

Since Windows has the strictest rules, files renamed by CrossRename will work on Linux and macOS without issues.

.. important::
   If files were created on Linux or macOS with Windows-forbidden characters (like ``<``, ``>``, ``:``, etc.),
   Windows cannot see those characters—the filenames appear mangled or stripped. To fix these files, you must run CrossRename from the originating OS (or WSL for Linux files), not from Windows.

`back to introduction  <introduction_>`__

Why did I build this?
---------------------

So I was dual-booting Windows 10 and Lubuntu 22.04, and one day I'm trying to move some files between the two systems.
Five files just wouldn't copy over because of what I later found out were the differences in Windows and Linux's file
naming rules.

That got me thinking because I'd already built a Python package that had to deal with some file creation and renaming (
It's called `FicImage <https://github.com/Jemeni11/ficimage>`__, please check it out 🫶) before, so I had an idea or two
about how to go about this.

Long story short, I got annoyed enough to build CrossRename. Now I don't have to deal with file naming headaches when
switching between systems.

.. note::
   I'm no longer dual booting. I'm using Windows 11 now. I do have WSL2 and that's what I use for testing.
   I don't know if there'll be any difference in the way the tool works on a native Linux system.

   macOS support is theoretical but should work since the tool uses the most restrictive ruleset (Windows).

   If you test on macOS, please report any issues!

`back to introduction  <introduction_>`__

Contributing
------------

Contributions are welcome! If you'd like to improve CrossRename please feel free to submit a pull request.

**Especially welcome:**

- macOS/APFS testing and feedback (currently untested on real macOS hardware)
- Linux testing and feedback (on native linux)
- Edge case handling for Unicode normalization differences
- Performance improvements for large directory trees
- Other Operating Systems
- Any other thing I forgot to list here

`back to introduction  <introduction_>`__

Wait a minute, who are you?
---------------------------

Hello there! I'm Emmanuel Jemeni, and while I primarily work as a Frontend Developer,
Python holds a special place as my first programming language.
You can find me on various platforms:

- `LinkedIn <https://www.linkedin.com/in/emmanuel-jemeni>`__
- `GitHub <https://github.com/Jemeni11>`__
- `BlueSky <https://bsky.app/profile/jemeni11.bsky.social>`__
- `Twitter/X <https://twitter.com/Jemeni11_>`__

`back to introduction  <introduction_>`__

License
-------

`MIT License <https://github.com/Jemeni11/CrossRename/blob/main/LICENSE>`__

`back to introduction  <introduction_>`__

Changelog
---------

`Changelog <https://github.com/Jemeni11/CrossRename/blob/main/CHANGELOG.md>`__

`back to introduction  <introduction_>`__
