P4CaseSync User Manual

P4CaseSync

P4CaseSync is a small tool that synchronizes and corrects path and filename capitalization before Perforce submission.
On Windows, P4 often weakens case distinctions, causing uploaded directories and files to become lowercase. This tool corrects the file paths listed by p4 opened using actual capitalization on the local disk, allows manual adjustments, and applies changes as p4 move operations in one click.

• Scans opened files in a Changelist (or default)
• Uses p4 where mapping and reads actual local capitalization, correcting each level of the entire path
• Color-coded list for easy identification
  • Gray: Before and after are identical; no change needed
  • Green: Matches the automatically corrected value
  • Red: Manually edited by the user and differs from the automatic value
• Double-click the entire row to open a centered edit dialog
• Performs a consistency check after applying changes; if inconsistent, automatically tries a two-step move fallback, and reports failure if inconsistency remains
• Shows only edit / add / move/add, automatically hiding deletion actions

• The top shows a color legend and an “Only show files needing changes” toggle
• Rows show “Before / After”; double-click a row to edit “After”

• Windows (recommended)
• Python 3.8+
• Installed Perforce CLI p4, available from the command line
• Tkinter (included with Python)
• PyInstaller (optional for development/packaging)

git clone https://github.com/<your-org-or-user>/P4CaseSync.git
cd P4CaseSync

# 新建环境（示例用 python 3.11）
conda create -n p4casesync python=3.11 -y
conda activate p4casesync

# 安装打包所需（运行本工具本身无需第三方包；打包需要 PyInstaller）
pip install -r requirements.txt
# 如果你没有 requirements.txt，可先： pip install pyinstaller

# Windows PowerShell
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

# macOS/Linux
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Note: Running the project requires only the standard library and p4; requirements.txt generally needs only pyinstaller for packaging.
If the file is missing, create one containing only:

pyinstaller>=6

# 在激活环境下
python Main.py

This project uses dynamic path imports, so hidden imports must be specified through a spec file.

pyinstaller P4CaseSync.spec

The generated executable is at dist/P4文件名大小写同步工具.exe

P4CaseSync.spec is configured for:

• Single-file packaging (--onefile)
• No console window (--noconsole)
• Hidden imports: LoginUI, MainUI, Core
• Output filename: P4文件名大小写同步工具

To change settings such as filename or icon, edit P4CaseSync.spec:

• Rename: Find the line name='P4文件名大小写同步工具'
• Add an icon: Change icon=None to icon='icon.ico'
• Show the console: Change console=False to console=True for debugging

Do not mix command-line packaging options with a spec file:

# ❌ 错误示例
pyinstaller -F -w P4CaseSync.spec  # 会报错

# ✅ 正确用法
pyinstaller P4CaseSync.spec

The project uses InjectSysPath() to add module paths dynamically. PyInstaller cannot automatically identify modules under Source/UI and Source/Logic. The spec file explicitly declares these modules through hiddenimports to ensure packaging succeeds.

1. Open the tool and select the Changelist to process (default: default).
2. The tool lists files automatically:
   • Gray: Before and after match; skipped
   • Green: Automatically corrected to actual local capitalization
   • Red: Manually edited and differs from the automatic value
3. To adjust a path, double-click its row and edit the “After” path in the dialog.
4. Click Apply Changes: the tool runs p4 move sequentially and checks consistency, using the two-step move fallback if necessary.
5. Submit normally in P4V or from the command line.

Q1: Why do large gray bars or ghosting appear?
A: This has been fixed. Refreshing the list destroys all child widgets, including separators, to prevent remnants.

Q2: Why is “X” sometimes shown instead of “✔”?
A: This depends on the system theme. Windows vista/xpnative themes are preferred. Custom icons are another option if needed.

Q3: What if the local path does not exist?
A: The tool corrects capitalization through the deepest accessible parent directory where possible. Unresolvable portions remain unchanged and can be edited manually.

Q4: What if submission includes deletion actions?
A: Deletion actions (delete/move/delete) are filtered by default; only edit/add/move/add are shown.

• Color decision rules (final version):
  1. After == Before → Gray
  2. After != Before and After == Automatic value → Green
  3. After != Automatic value → Red
• Double-click the entire row to edit; colors refresh immediately afterward
• Consistency check failure → Automatically try a two-step move (temporary name → target name), then check again

“Minicode virtual environment” usually refers to Miniconda. Both Conda and pip/venv approaches are provided below.

Export (prefer history to avoid unrelated packages):

# 当前激活 p4casesync 环境
conda env export > environment.yml

Restore:

conda env create -f environment.yml
conda activate p4casesync

Export:

# 激活你的 venv 后
pip freeze > requirements.txt

Restore:

# Windows
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

# macOS/Linux
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

MIT License

Thanks to all developers using and providing feedback on P4CaseSync. Open an Issue for problems or contribute improvements through a PR.