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 and Windows.
`Explore the repo » <https://github.com/Jemeni11/CrossRename>`__
Table of Contents
-----------------
- `Introduction`_
- `Features`_
- `Installation`_
- `Usage`_
- `Examples`_
- `Safety First`_
- `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 and Windows systems.
It ensures that your file names are compatible with both operating systems, eliminating naming conflicts
when transferring files between different environments.
`back to top <crossrename_>`__
Features
--------
- Sanitizes file names to be Windows-compatible (and thus Linux-compatible)
- **NEW:** 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 top <crossrename_>`__
Installation
------------
From PyPI (Using PIP)
~~~~~~~~~~~~~~~~~~~~~
.. code-block:: bash
pip install CrossRename
`back to top <crossrename_>`__
Usage
-----
.. code-block:: text
usage: crossrename [-h] [-p PATH] [-v] [-u] [-r] [-d] [-D] [--force] [--credits]
CrossRename: Harmonize file and directory names for Linux and Windows.
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!
--force Skip safety prompts (useful for automated scripts)
--credits Show credits and support information
`back to top <crossrename_>`__
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
Check for an update:
.. code-block:: bash
crossrename -u
Show credits and project information:
.. code-block:: bash
crossrename --credits
`back to top <crossrename_>`__
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 /build/output -r -D --force
Directory renaming is particularly powerful and potentially disruptive since it changes folder paths that other
applications might reference.
`back to top <crossrename_>`__
Why did I build this?
---------------------
.. warning::
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.
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.
`back to top <crossrename_>`__
Contributing
------------
Contributions are welcome! If you'd like to improve CrossRename or add support for
other operating systems (like macOS), please feel free to submit a pull request.
`back to top <crossrename_>`__
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 top <crossrename_>`__
License
-------
`MIT License <https://github.com/Jemeni11/CrossRename/blob/main/LICENSE>`__
`back to top <crossrename_>`__
Changelog
---------
`Changelog <https://github.com/Jemeni11/CrossRename/blob/main/CHANGELOG.md>`__
`back to top <crossrename_>`__
Raw data
{
"_id": null,
"home_page": null,
"name": "CrossRename",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "files, folders, rename, linux, windows, transferring, filename",
"author": null,
"author_email": "\"Emmanuel C. Jemeni\" <jemenichinonso11@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ed/44/25b2596728554789340d1c6118964f5b3e9e1c4ad04e233f2af009a5508e/crossrename-1.2.1.tar.gz",
"platform": null,
"description": "CrossRename\r\n===========\r\n\r\n.. image:: https://github.com/Jemeni11/CrossRename/blob/master/logo.png?raw=true\r\n :alt: CrossRename Logo\r\n :width: 128px\r\n :height: 128px\r\n :align: center\r\n\r\n\r\nHarmonize file and directory names for Linux and Windows.\r\n\r\n`Explore the repo \u00bb <https://github.com/Jemeni11/CrossRename>`__\r\n\r\n\r\nTable of Contents\r\n-----------------\r\n\r\n- `Introduction`_\r\n- `Features`_\r\n- `Installation`_\r\n- `Usage`_\r\n\r\n - `Examples`_\r\n - `Safety First`_\r\n\r\n- `Why did I build this?`_\r\n- `Contributing`_\r\n- `Wait a minute, who are you?`_\r\n- `License`_\r\n- `Changelog`_\r\n\r\nIntroduction\r\n------------\r\n\r\nCrossRename is a command-line tool designed to harmonize file and directory names across Linux and Windows systems.\r\nIt ensures that your file names are compatible with both operating systems, eliminating naming conflicts\r\nwhen transferring files between different environments.\r\n\r\n`back to top <crossrename_>`__\r\n\r\nFeatures\r\n--------\r\n\r\n- Sanitizes file names to be Windows-compatible (and thus Linux-compatible)\r\n- **NEW:** Optionally renames directories to be cross-platform compatible\r\n- Handles both individual files and entire directories\r\n- Supports recursive renaming of files in subdirectories\r\n- Preserves file extensions, including compound extensions like .tar.gz\r\n- Provides informative logging\r\n- Provides a dry-run mode to preview renaming changes without executing them\r\n- Interactive safety warnings with option to skip for automation\r\n- Skips recursive symlinks to avoid infinite loops\r\n\r\n`back to top <crossrename_>`__\r\n\r\nInstallation\r\n------------\r\n\r\nFrom PyPI (Using PIP)\r\n~~~~~~~~~~~~~~~~~~~~~\r\n\r\n.. code-block:: bash\r\n\r\n pip install CrossRename\r\n\r\n`back to top <crossrename_>`__\r\n\r\nUsage\r\n-----\r\n\r\n.. code-block:: text\r\n\r\n usage: crossrename [-h] [-p PATH] [-v] [-u] [-r] [-d] [-D] [--force] [--credits]\r\n\r\n CrossRename: Harmonize file and directory names for Linux and Windows.\r\n\r\n options:\r\n -h, --help show this help message and exit\r\n -p, --path PATH The path to the file or directory to rename.\r\n -v, --version Prints out the current version and quits.\r\n -u, --update Check if a new version is available.\r\n -r, --recursive Rename all files in the directory path given and its subdirectories. When used with -D, also renames subdirectories.\r\n -d, --dry-run Perform a dry run, logging changes without renaming.\r\n -D, --rename-directories Also rename directories to be cross-platform compatible. Use with caution!\r\n --force Skip safety prompts (useful for automated scripts)\r\n --credits Show credits and support information\r\n\r\n`back to top <crossrename_>`__\r\n\r\nExamples\r\n~~~~~~~~\r\n\r\nRename a single file:\r\n\r\n.. code-block:: bash\r\n\r\n crossrename -p /path/to/file.txt\r\n\r\nRename all files in a directory (and its subdirectories):\r\n\r\n.. code-block:: bash\r\n\r\n crossrename -p /path/to/directory -r\r\n\r\nRename all files AND directories recursively:\r\n\r\n.. code-block:: bash\r\n\r\n crossrename -p /path/to/directory -r -D\r\n\r\nRename a single directory:\r\n\r\n.. code-block:: bash\r\n\r\n crossrename -p /path/to/problematic_directory -D\r\n\r\nPerform a dry run to preview renaming changes without executing them:\r\n\r\n.. code-block:: bash\r\n\r\n crossrename -p /path/to/directory -r -D -d\r\n\r\nSkip safety prompts for automated scripts:\r\n\r\n.. code-block:: bash\r\n\r\n crossrename -p /path/to/directory -r -D --force\r\n\r\nCheck for an update:\r\n\r\n.. code-block:: bash\r\n\r\n crossrename -u\r\n\r\nShow credits and project information:\r\n\r\n.. code-block:: bash\r\n\r\n crossrename --credits\r\n\r\n`back to top <crossrename_>`__\r\n\r\nSafety First\r\n~~~~~~~~~~~~\r\n\r\n.. warning::\r\n Always run with ``--dry-run`` first!\r\n\r\nCrossRename will show interactive safety warnings before making any changes to help prevent accidental data loss.\r\nHowever, it's strongly recommended to:\r\n\r\n1. **Run a dry run first** to preview what will be changed:\r\n\r\n .. code-block:: bash\r\n\r\n crossrename -p /your/path -r -D -d\r\n\r\n2. **Backup your data** before running the tool on important files\r\n\r\n3. **Use** ``--force`` **flag** for automation in CI/CD pipelines:\r\n\r\n .. code-block:: bash\r\n\r\n crossrename -p /build/output -r -D --force\r\n\r\nDirectory renaming is particularly powerful and potentially disruptive since it changes folder paths that other\r\napplications might reference.\r\n\r\n`back to top <crossrename_>`__\r\n\r\nWhy did I build this?\r\n---------------------\r\n\r\n.. warning::\r\n I'm no longer dual booting. I'm using Windows 11 now. I do have WSL2 and that's what I use for testing.\r\n I don't know if there'll be any difference in the way the tool works on a native Linux system.\r\n\r\nSo I was dual-booting Windows 10 and Lubuntu 22.04, and one day I'm trying to move some files between the two systems.\r\nFive files just wouldn't copy over because of what I later found out were the differences in Windows and Linux's file\r\nnaming rules.\r\n\r\nThat got me thinking because I'd already built a Python package that had to deal with some file creation and renaming (\r\nIt's called `FicImage <https://github.com/Jemeni11/ficimage>`__ please check it out \ud83e\udef6) before, so I had an idea or two\r\nabout how to go about this.\r\n\r\nLong story short, I got annoyed enough to build CrossRename. Now I don't have to deal with file naming headaches when\r\nswitching between systems.\r\n\r\n`back to top <crossrename_>`__\r\n\r\nContributing\r\n------------\r\n\r\nContributions are welcome! If you'd like to improve CrossRename or add support for\r\nother operating systems (like macOS), please feel free to submit a pull request.\r\n\r\n`back to top <crossrename_>`__\r\n\r\nWait a minute, who are you?\r\n---------------------------\r\n\r\nHello there! I'm Emmanuel Jemeni, and while I primarily work as a Frontend Developer,\r\nPython holds a special place as my first programming language.\r\nYou can find me on various platforms:\r\n\r\n- `LinkedIn <https://www.linkedin.com/in/emmanuel-jemeni>`__\r\n- `GitHub <https://github.com/Jemeni11>`__\r\n- `BlueSky <https://bsky.app/profile/jemeni11.bsky.social>`__\r\n- `Twitter/X <https://twitter.com/Jemeni11_>`__\r\n\r\n`back to top <crossrename_>`__\r\n\r\nLicense\r\n-------\r\n\r\n`MIT License <https://github.com/Jemeni11/CrossRename/blob/main/LICENSE>`__\r\n\r\n`back to top <crossrename_>`__\r\n\r\nChangelog\r\n---------\r\n\r\n`Changelog <https://github.com/Jemeni11/CrossRename/blob/main/CHANGELOG.md>`__\r\n\r\n`back to top <crossrename_>`__\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Harmonize file and directory names for Linux and Windows.",
"version": "1.2.1",
"project_urls": {
"Bug Tracker": "https://github.com/Jemeni11/CrossRename/issues",
"Changelog": "https://github.com/Jemeni11/CrossRename/blob/master/CHANGELOG.md",
"Funding": "https://buymeacoffee.com/jemeni11",
"Homepage": "https://github.com/Jemeni11/CrossRename"
},
"split_keywords": [
"files",
" folders",
" rename",
" linux",
" windows",
" transferring",
" filename"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ddb755c266051404977e4cdc57d6a23d05d4011afaf633ef20b48591317c83a7",
"md5": "e4c502080c1115efbfd2cf318b0c0994",
"sha256": "8a65815ab64b1b290a5269107890879a7ce977e91591e2a46c2ec6f806b80333"
},
"downloads": -1,
"filename": "crossrename-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e4c502080c1115efbfd2cf318b0c0994",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 9624,
"upload_time": "2025-08-03T17:01:47",
"upload_time_iso_8601": "2025-08-03T17:01:47.031176Z",
"url": "https://files.pythonhosted.org/packages/dd/b7/55c266051404977e4cdc57d6a23d05d4011afaf633ef20b48591317c83a7/crossrename-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ed4425b2596728554789340d1c6118964f5b3e9e1c4ad04e233f2af009a5508e",
"md5": "50853252aea65dbaa63be087a0f3bf22",
"sha256": "3e6f420a416b6a2ba542de57783833130fb27d97e00e1f1632ee6605fd0401f2"
},
"downloads": -1,
"filename": "crossrename-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "50853252aea65dbaa63be087a0f3bf22",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 9078,
"upload_time": "2025-08-03T17:01:49",
"upload_time_iso_8601": "2025-08-03T17:01:49.529303Z",
"url": "https://files.pythonhosted.org/packages/ed/44/25b2596728554789340d1c6118964f5b3e9e1c4ad04e233f2af009a5508e/crossrename-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 17:01:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Jemeni11",
"github_project": "CrossRename",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "crossrename"
}
JSON
