git4subeditor 0.1.20__py3-none-any.whl

git4subeditor-0.1.20.dist-info/METADATA

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: git4subeditor
+Version: 0.1.20
+Summary: Convert Barotrauma .sub submarine files into Git-friendly text
+Keywords: barotrauma,submarine,git,modding
+Author: Yinjie
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: ruff>=0.17 ; extra == 'dev'
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/Yinjie1/Git4SubEditor
+Project-URL: Repository, https://github.com/Yinjie1/Git4SubEditor
+Project-URL: Issues, https://github.com/Yinjie1/Git4SubEditor/issues
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# Git4SubEditor
+> Git for Submarine Editor
+
+一个 CLI 工具, 把 Barotrauma 的 `.sub` 潜艇文件转换为适合 Git 版本追踪的文本格式, 也支持将其转回 `.sub` 文件.
+
+> [!warning]
+> 如果你打算将此程序应用于你正在开发的项目, 请先进行**备份**, 以免发生不可挽回的灾难性事故.
+
+> [!note]
+> **后续计划**
+> - [ ] 我希望能集成一个Git GUI到游戏中, 并直接在潜艇编辑器中可视化不同版本潜艇的差异, 但我不熟悉这个游戏的接口, 也不会C#/Lua, 如果有感兴趣的大佬可以试试.
+> - [x] 自动初始化工作区 `git4subeditor init`, 自动添加 `.gitignore` 等
+> - [x] 多语言
+> - [ ] agent skill, 让 ai 根据 `git diff` 拟定提交说明等
+> - [x] 历史记录
+> - [x] Tab 补全
+
+## 为什么需要 Git
+1. Git 的版本控制, 并不是每个版本都备份一个副本, 而是记录两个版本间的 diff, 这样不仅版本仓库体积非常小, 而且可以很方便地看出每次都做了哪些改动. 又或者哪天搞砸了, 也可以回退到之前的任意版本.
+    > 就像 Git 官网里提到的: "Git 能高效地存储仓库历史. 截至 2025 年, 当前版本的 Linux 内核源代码大小为 1.7 GB. Git 仅用 5.5 GB 就存储了 Linux 项目的完整历史 (140 万次提交)."
+2. 可以上传到远程托管平台, 如 Github, Gitee 等, 这是一种更安全的"云同步", 同时也方便进行多人合作开发.
+
+## 为什么需要这个工具
+
+1. `.sub` 实际上是 gzip 压缩的单个 `xml` 文件. 直接提交 `.sub` 时, Git 只能看到二进制文件发生了变化, 无法审查具体改动.
+2. 解压后的 `xml` 中, 潜艇预览图是以源码的形式存放在根节点的 `previewimage` 属性里, 往往会让第一行长达几十万字符. 只要改动附近的内容(例如每次改动潜艇, 同一行`checkval`的值都会变化), 就会产生巨大的单行 diff.
+    > `checkval` 是潜艇保存时写入的随机整数, 用于多人战役校验潜艇文件; 本工具不会修改它, 因此每次在游戏中保存后, 根节点仍会出现一行 `checkval` 变化.
+1. 此外在 `xml` 中, 由于游戏内部把一些属性当作无序集合保存, 而每次保存潜艇, 这些值的顺序都可能变化, 导致大量无意义 diff.
+
+
+## 该程序做了什么
+将潜艇 `.sub` 文件解压并转成 Git 友好的 `xml` 文件, 也支持将 `xml` 打包成 `.sub`
+1. 将预览图单独导出, 并相对链接引用预览图, 以防每次改动潜艇都要巨大的单行 diff.
+2. 自动按字母顺序排序下列属性的值, 以防每次保存潜艇顺序改变导致大量无意义 diff
+   - Tags
+   - requireditem 的 items
+   - excludedidentifiers
+   - DisallowedUpgrades
+   - DisallowAttachingOverTags
+   - ContainableRestrictions
+   - idcardtags
+   - outposttags
+
+---
+
+## 安装教程 (Windows)
+> [!tip]
+> 要是实在不会, 就把该文档发给 ai, 让 ai 帮忙装.
+
+### 1. 安装 Git for Windows
+直接到 Git [官网](https://git-scm.com/install/windows)上下载
+### 2. 安装 Python 环境(可选)
+安装包管理工具 [uv](https://docs.astral.sh/uv/), 打开 CMD/PowerShell:
+```bash
+winget install uv
+# 检查是否安装成功
+uv --version
+```
+uv 默认把解释器/包/工具都装在C盘, 如果想改安装目录, 可以改环境变量`UV_CACHE_DIR`, `UV_PYTHON_INSTALL_DIR`, `UV_TOOL_BIN_DIR`, `UV_TOOL_DIR`, 运行以下命令检查是否修改成功:
+```bash
+uv python dir
+uv cache dir
+uv tool dir
+```
+运行以下命令并重启终端, 来把`UV_TOOL_BIN_DIR`添加到PATH:
+```bash
+uv tool update-shell
+```
+安装一个 Python 解释器:
+```bash
+# 最后一个是版本, 版本不要太低
+uv python install 3.15
+```
+### 3. 安装 Git4SubEditor
+从 GitHub 安装到 uv 的独立工具环境, 不会污染 Python 全局环境:
+
+```bash
+uv tool install "git4subeditor @ git+https://github.com/Yinjie1/Git4SubEditor.git"
+# 检查是否安装成功
+uv tool list
+git4subeditor --version
+```
+
+---
+
+## 快速开始
+你的潜艇Mod目录位于`Barotrauma\LocalMods\`中, 可以在游戏内的模组选择界面, 点击你的潜艇Mod右侧的"笔"图标快速打开.  
+运行这个工具需在当前Mod目录或子目录下打开终端(右键目录背景->在终端中打开), 反正必须确保终端的工作目录是在你要修改的Mod的目录.
+### 1. 初始化工作目录
+Mod目录中需要有一个 Git 仓库, 如果没有, 可以运行以下命令初始化仓库:
+```bash
+git init
+```
+接着运行以下命令, 初始化 git4subeditor 项目:
+```bash
+git4subeditor init
+```
+此过程会自动生成/修改 `.gitignore` 文件, 确保 Git 忽略追踪 `*.sub`, `*.bak`, `*.png`, `history` 这4种文件, 你也可以手动添加你要忽略的文件.  
+还会生成一个项目配置文件 `git4subeditor.xml`, 里面储存了用户偏好及已注册潜艇信息:
+```xml
+<?xml version='1.0' encoding='utf-8'?>
+<git4subeditor>
+  <projectName>test</projectName>
+  <language>cn</language>
+  <gitRepo>../..</gitRepo>
+  <modRoot>../..</modRoot>
+  <version>0.1.19</version>
+  <submarines>
+    <submarine name="自定义名称" path="../../test/Git test.sub" preview="../../test/Git test.png" hash="..." />
+    <submarine path="../Git test2.sub" preview="../Git test2.png" hash="..." />
+    <submarine path="Git test3.sub" preview="Git test3.png" hash="..." />
+    <submarine path="tttt/Git test3.sub" preview="tttt/Git test4.png" hash="..." />
+  </submarines>
+</git4subeditor>
+```
+### 2. 交互模式
+该程序提供 CLI 模式和交互模式, 前者适合 ai 使用, 后者提供了人类可读的界面, 并且交互逻辑更加简单, 还提供了命令补全和历史记录功能, 运行以下命令启动交互模式:
+```bash
+git4subeditor
+```
+你将会看到如以下的界面
+```
+ ██████╗ ██╗████████╗    ██╗  ██╗    by Yinjie
+██╔════╝ ██║╚══██╔══╝    ██║  ██║    0.1.19
+██║  ███╗██║   ██║       ███████║
+██║   ██║██║   ██║       ╚════██║
+╚██████╔╝██║   ██║            ██║
+ ╚═════╝ ╚═╝   ╚═╝            ╚═╝
+
+███████╗██╗   ██╗██████╗ ███████╗██████╗ ██╗████████╗ ██████╗ ██████╗
+██╔════╝██║   ██║██╔══██╗██╔════╝██╔══██╗██║╚══██╔══╝██╔═══██╗██╔══██╗
+███████╗██║   ██║██████╔╝█████╗  ██║  ██║██║   ██║   ██║   ██║██████╔╝
+╚════██║██║   ██║██╔══██╗██╔══╝  ██║  ██║██║   ██║   ██║   ██║██╔══██╗
+███████║╚██████╔╝██████╔╝███████╗██████╔╝██║   ██║   ╚██████╔╝██║  ██║
+╚══════╝ ╚═════╝ ╚═════╝ ╚══════╝╚═════╝ ╚═╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝
+
+项目: test | Git 仓库: ../.. | 模组根目录: ../..
+CWD: path_to/current_work_directory
+../..
+├── ../../test
+│   └── 自定义名称: Git test.sub
+└── ..
+    ├── Git test2: Git test2.sub (M)
+    └── .
+        ├── Git test3: Git test3.sub
+        └── tttt
+            └── Git test4: Git test4.sub (U)
+
+命令:
+  init                        初始化/更新工作区
+  tree                        递归搜索并显示仓库下所有潜艇
+  export <file.sub> [-o DIR]  解压 .sub 并转为 Git 友好的 XML
+  pack <file.xml> [-o FILE]   打包 XML 为 .sub
+  unpack <file.sub> [-o DIR]  仅解压 .sub 为原始 XML
+  q                           退出交互模式
+
+Tab 补全 · ↑↓ 历史 · Ctrl-R 搜索 · Ctrl-D 退出 · ? 帮助
+g4s:test>
+```
+其中的潜艇 `.sub` 文件目录树, 是以 **Git 仓库**所在目录为根目录递归搜索得到的, 目录以相对路径显示. 示例中的目录结构是为了展示刻意制造的, 不建议搞这么复杂.  
+其中未注册潜艇带有红色标识 `(U)`. 已注册潜艇在初始化或 `export` 时, 会自动计算并记录哈希值到 `git4subeditor.xml` 中, 生成目录树时会再次计算哈希, 若潜艇发生改动, 哈希会发生改变, 发生改动的潜艇带有黄色标识 `(M)`.
+### 3. sub 转 XML
+若你的潜艇文件为`test.sub`, 执行命令:
+```bash
+# 交互模式
+export "test.sub"
+# CLI 模式
+git4subeditor export "test.sub"
+```
+将会得到2个文件: `test.xml`, `test.png`. 其中`test.xml`就是 Git 要追踪的文件.  
+如果已经进行项目初始化(即当前目录有 `git4subeditor.xml`), 可通过以下命令自动导出所有发生改动的已注册 `.sub` 文件:
+```bash
+# 交互模式
+export
+# CLI 模式
+git4subeditor export
+```
+
+### 4. 用 Git 管理 XML
+> [!tip]
+> 要是实在不会, 就让 ai 帮忙弄, ai 很擅长使用 CLI. 像提交, 回退版本, 比较两个版本的差异, 写提交说明, 都可以问 ai.
+
+该程序不集成操作 Git 仓库的功能, 因为已经有很多成熟的 Git GUI 工具, 重写一遍不仅工作量大, 而且可能还更难用, bug更多, 把仓库搞坏就麻烦了.  
+对于不熟悉命令行的小白, 可以安装一些集成了 Git GUI 的 IDE, 用以**可视化差异**与**提交**修改. 我建议用 [VSCode](https://code.visualstudio.com/Download) (选System Installer), Git for Windows 也自带了一个 GUI, 但没那么好用.
+关于 Git 的使用, 可以看这个快速入门[教程](https://chriswenchen.github.io/theory-computing-physics-guide/docs/git), 最常用的就几个 CLI 命令:
+```bash
+# 初始化版本库
+git init
+# 查看未提交改动(按q退出)
+git diff HEAD
+# 暂存所有改动
+git add .
+# 查看状态
+git status
+# 提交暂存区的内容到版本库
+git commit -m "这里写提交说明"
+```
+
+### 5. XML 转 sub
+如果要回退版本, 用 Git 把 `xml` 回退到指定的版本, 再用以下命令转成 `.sub`文件:
+```bash
+# 交互模式
+pack "test.xml"
+# CLI 模式
+git4subeditor pack "test.xml"
+```
+如果 `test.sub` 已存在, 会先备份为: `test.sub.bak` (给你一个后悔的机会), 然后覆盖写入新的 `test.sub`.

git4subeditor-0.1.20.dist-info/RECORD

@@ -0,0 +1,17 @@
+git4subeditor/__init__.py,sha256=e-HPVIES9lRhcY5ZKZTTqwlalk-hhDc-nllm6JaSjYY,802
+git4subeditor/__main__.py,sha256=50mWt6RKY21_lcORXMZR3ybM8_GgZzlfXELlXG0L9cg,134
+git4subeditor/cli.py,sha256=mkNekFXvDB7yI-p8XZvmt2TFOz6aUCe4bwIrlFNOyr0,21657
+git4subeditor/gitformat.py,sha256=kflvieh291yXZGv4EyQPUcciYDB8mLqDNcrKE0t0YzI,14124
+git4subeditor/l10n.py,sha256=Dh0GZzXrD4N5Jy3oY0fFBvefJcB5ISvgr11tGj0GgV4,3103
+git4subeditor/locales/cn.xml,sha256=Ltm6cSMc9K5tPdjvED2gZopXzQN6yqovJLrPMHiNzRM,8829
+git4subeditor/locales/en.xml,sha256=tV6uS1Xf85mCWKMxpR0WJ4moDcWg74_mmEVhlEVBRo0,9162
+git4subeditor/locales/ru.xml,sha256=hSbpqo3WY6Xz7jhhR_AWaJ2LcDmcCLfm5PoCyvuc-SQ,13348
+git4subeditor/repl.py,sha256=P288cVQteoxqAchxuyLwoTyGxc1eP0eteZ0UsvC6ri0,7852
+git4subeditor/subfile.py,sha256=UD0ATq1hh--S7GFS7KWYmOnkJizITfmM3q2I2xfqE-0,5467
+git4subeditor/utils.py,sha256=5lLJjqqoANQoxzOBwihPMnVOvdfA0GEVXY_y5w9hqOE,4683
+git4subeditor/workspace.py,sha256=JADeb9onhuAz0GtLYN3ZaDvvW4NgY7KpemT9xOdQ4Sc,30365
+git4subeditor-0.1.20.dist-info/licenses/LICENSE,sha256=TUgQviYtxTU6lo0cwLCuPYT3wcvSDyk4d4fsoRRnZug,1062
+git4subeditor-0.1.20.dist-info/WHEEL,sha256=MWx7psoF7KNST9G72pGtiBYuaXRXQXBk9pw5R6FzYko,80
+git4subeditor-0.1.20.dist-info/entry_points.txt,sha256=sRPU4lU95WjZ0HkvwL8bF020Ru4xzBEI1BDH4HITQoY,58
+git4subeditor-0.1.20.dist-info/METADATA,sha256=Mfxsic6QodNWwaLqX-R2z3oAFKaiBykCbvrZvlPNR8w,11312
+git4subeditor-0.1.20.dist-info/RECORD,,

git4subeditor-0.1.20.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.7
+Root-Is-Purelib: true
+Tag: py3-none-any

git4subeditor-0.1.20.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+git4subeditor = git4subeditor.cli:main
+

git4subeditor-0.1.20.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yinjie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.