From ea3e324c82d4c76638d53534a8f8d8d32fb8c5e0 Mon Sep 17 00:00:00 2001 From: 魏曹先生 <1992414357@qq.com> Date: Sat, 10 Jan 2026 18:01:52 +0800 Subject: Update README with new branding and detailed documentation --- README.md | 165 +++++++++++++++++++++++++++-------- README_zh_CN.md | 157 +++++++++++++++++++++++++++------ docs/Resources/Visual/Image1.png | Bin 0 -> 10233 bytes docs/Resources/Visual/Image2.png | Bin 0 -> 11266 bytes docs/Resources/Visual/Yizi_Icon.png | Bin 0 -> 71439 bytes docs/Resources/Visual/background.png | Bin 0 -> 693 bytes docs/images/Background.png | Bin 1209 -> 0 bytes docs/images/Header.png | Bin 1491 -> 0 bytes docs/images/Header_Large.png | Bin 7639 -> 0 bytes docs/images/Yizi.png | Bin 322 -> 0 bytes docs/images/Yizi_Large.png | Bin 21040 -> 0 bytes 11 files changed, 260 insertions(+), 62 deletions(-) create mode 100644 docs/Resources/Visual/Image1.png create mode 100644 docs/Resources/Visual/Image2.png create mode 100644 docs/Resources/Visual/Yizi_Icon.png create mode 100644 docs/Resources/Visual/background.png delete mode 100644 docs/images/Background.png delete mode 100644 docs/images/Header.png delete mode 100644 docs/images/Header_Large.png delete mode 100644 docs/images/Yizi.png delete mode 100644 docs/images/Yizi_Large.png diff --git a/README.md b/README.md index bcedff7..86c490a 100644 --- a/README.md +++ b/README.md @@ -1,81 +1,166 @@

- - JustEnoughVCS - + + JustEnoughVCS +

-

JustEnoughVCS

- Making version control easier than breathing! + Centralized Version Control for Multi-Structured Files

-

- - - + + +

+## Foreword +> [!Warning] +> +> `JustEnoughVCS` is under active development and there is no release plan yet. +> +> If you are interested in this project, feel free to [contact](#Support) us directly! + +> [!NOTE] +> +> `JustEnoughVCS` is designed for **asset content management** and is **not suitable for source code version control**. Its multi-structure, branch-less design philosophy makes it unsuitable for any project with strong structural dependencies. ## Introduction -If you are looking for a version control system that your team members can easily get started with, we highly recommend you give this a try. This version control system lives up to its name: "Just Enough," providing just what you need without creating excessive mental overhead. +`JustEnoughVCS` is a **centralized version control system** that focuses on providing a simple and flexible workflow for **asset management scenarios dominated by binary files**. It does not treat file paths as the identity of a file, but separates them into the relationship between **unique identity (what the file is)** and **path mapping (where the file is)**. +> [!TIP] +> +> If you wish to install directly, you can click [here](#Installation) -## Architecture -`JustEnoughVCS` is a **centralized** version control system, divided into two parts: the **client** and the **server**. +### 1. Struct Sheet System -> [!NOTE] -> -> This version control system addresses the problem of managing the structure and versions of binary assets and is not suitable for managing code and text. -> -> In the realm of code and text, there are other extremely mature and widely recognized SCM systems. +**Personal Struct Sheet** +`JustEnoughVCS` allows each member to establish their own **Struct Sheet**, which represents **that member's understanding of the files visible to them**. It does not and need not be known by other members what it looks like. Each member works within their own **Struct Sheet**, sharing the **visibility of files** with others only when necessary. +**Reference Sheet** -## Multi-File Structure +In the upstream repository (Upstream Vault) of `JustEnoughVCS`, a publicly visible **Reference Sheet** is maintained by the **repository administrator**. All members can query **the location of a file within the Reference Sheet** to facilitate a common understanding of the files. -It encourages users to place and manage their assets in their preferred way and share the **visibility** of files with other team members as needed. Since each member has their own structure, there's no need to worry about file moves affecting others. +

+ + JustEnoughVCS + +

+ The Reference Sheet is used to anchor the authoritative naming of files. +

+

-## Serialized Editing +### 2. Serialized Editing -At the same time, `JustEnoughVCS` manages permissions at the file granularity. At any given moment, only one member holds a file, meaning they have the **editing rights** for that file. After updating a file version, other members can discover the new version during the next status check and decide whether to update the latest version to their local workspace. +`JustEnoughVCS` adopts a **serialized editing model**, eliminating merge conflicts at their root. Our permission principle is: **Visible means readable, held means writable**. +When you hold a file, you have exclusive editing rights. Other members can see the current version but cannot edit simultaneously. Once you finish editing, the new version you submit is immediately available for everyone to fetch. +Serialized editing ensures there is only one "source of truth." If a member edits without holding the permission or based on an outdated version, the system will clearly mark these modifications as **invalid edits**, meaning they will not be accidentally committed or overwrite the valid version. -## Rejecting Ambiguous Mappings +Don't worry, the frontends of `JustEnoughVCS` ([Command Line, Desktop](#Installation)) provide clear and visible views to confirm file status. -When there is a **discrepancy** between the actual file structure and the recorded file structure, `JustEnoughVCS` will prevent you from tracking the file's version. You need to clearly explain your local structural changes before you can proceed. -## Roadmap +### 3. Architecture + +`JustEnoughVCS` is a centralized version control system, divided into a **server** and **clients**. The local workspace is merely a file copy used for recording modifications and updates. + +**Upstream Vault** -### Core Library +The Upstream Vault records the following information: -- [ ] Incremental file updates and storage -- [ ] Multiple reference tables +1. Upstream Vault configuration information. +2. Member registration information and public keys. +3. Struct Sheets + 1. Current holder. + 2. Mapping relationships. +4. File metadata + 1. Current holder. + 2. Version sequence. +5. File historical version storage **(full, uncompressed)**. -### Extension Tools +**Local Workspace** + +The Local Workspace records the following information: + +1. Workspace configuration information. +2. Local cache of upstream vault metadata. +3. Local cache of struct sheets: used to compare local and upstream differences. +4. Local struct sheet: used to analyze workspace changes. +5. Physical files. + +

+ + JustEnoughVCS + +

+ Relationship between Vault and Workspace. +

+

+ + + +## Installation + +This repository is the core library of `JustEnoughVCS` and does not provide any interactive functionality. + +Please go to the corresponding repositories to download or build the `JustEnoughVCS` frontends: + +- [Command Line Frontend](https://github.com/JustEnoughVCS/CommandLine) +- [Desktop Frontend](https://github.com/JustEnoughVCS/Desktop) **In Development** + + + +## Roadmap + +- [ ] Core Features + - [x] Sheet Management + - [x] Tracking + - [x] Alignment + - [x] Sharing + - [x] Referencing + - [x] Administrator Tools + - [ ] Version Jumping + - [ ] Version Freezing + - [ ] Borrowing Tool + +- [ ] Command Line + - [ ] Full Core Feature Wrapping + - [x] Help + - [x] Completion + - [ ] Embedded Documentation + - [ ] JSON Output + +- [ ] Desktop + - [ ] Full Core Feature Wrapping + - [x] Command Line Wrapper + - [ ] Themes + +- [ ] 2026 Plan + - [ ] Desktop Support **Current Phase** + - [ ] Standardize Core & CLI Code + - [ ] Improve Async & Concurrency Support + - [ ] Storage Optimization + - [ ] Distributed Content Storage, Centralized Permission Management -- [x] Command-line client -> [CommandLine](https://github.com/JustEnoughVCS/CommandLine ) -- [ ] Desktop client -> [JVDesktop](https://github.com/JustEnoughVCS/JVDesktop ) -- [ ] Declarative asset management -> [JVRefs](https://github.com/JustEnoughVCS/AssetsConfig) (Currently Private) -- [ ] File merger -> [JVBinMerger](https://github.com/JustEnoughVCS/BinMerger) (Currently Private) ## Support -Encountering any issues or have suggestions while using JustEnoughVCS? +Encountered any issues or have suggestions while using JustEnoughVCS? -- Please submit them to the https://github.com/JustEnoughVCS/VersionControl/issues page. We will promptly address your feedback. +- Please submit them to the https://github.com/JustEnoughVCS/VersionControl/issues page. We will address your feedback promptly. @@ -83,8 +168,18 @@ Encountering any issues or have suggestions while using JustEnoughVCS? This project is licensed under the **MIT License**. -For the full license terms, please refer to the ./LICENSE-MIT.md file in the project root directory. +For the full license terms, please see the *./LICENSE-MIT.md* file in the project root directory. --- Finally, thank you for your interest in `JustEnoughVCS`! + + + +## A Few Words + +> Why name it `JustEnoughVCS`? +> +> If you think it sounds like a name a Minecraft Mod would have, you guessed right! +> +> The inspiration actually came from `JustEnoughItems` 😄 diff --git a/README_zh_CN.md b/README_zh_CN.md index 6f7a495..de96c33 100644 --- a/README_zh_CN.md +++ b/README_zh_CN.md @@ -1,13 +1,12 @@

- JustEnoughVCS + JustEnoughVCS

-

JustEnoughVCS

- 让版本控制比呼吸还简单！ + 多文件结构的集中式版本控制

@@ -17,58 +16,152 @@

- ## 写在开头 -如果您正在寻找一款让您团队成员可以轻松上手的版本控制，那么我们非常推荐您尝试一下。这款版本控制正如其名字讲述的那样：“刚好够用”，不产生过多的心智负担。 - +> [!Warning] +> +> `JustEnoughVCS` 还在稳步开发，目前并无发布的计划 +> +> 如果您对该项目感兴趣，欢迎直接[联系](#支持)我们！ +> [!NOTE] +> +> `JustEnoughVCS` 为**资产内容管理**而设计，并**不适合作为源代码版本控制**，多结构、无分支的设计理念决定了其无法胜任任何强结构依赖的项目。 -## 架构 +## 介绍 -`JustEnoughVCS` 是一款 **集中式** 的版本控制，分为 **客户端** 和 **服务端** 两个部分。 +`JustEnoughVCS` 是一款 **集中式版本控制系统**，它专注于为 **以二进制文件为主的资产管理场景** 提供简洁、自由的工作流。它不将文件路径视为文件的身份，而是分离成 **唯一身份（文件是什么）** 和 **路径映射（文件在哪）** 的关系。 -> [!NOTE] -> -> 该版本控制解决的是二进制资产的结构和版本管理的问题，不适合管理代码和文本。 +> [!TIP] > -> 在代码和文本领域，有极为成熟且被认可的其他 SCM 系统。 +> 若您希望直接安装，可以点击[此处](#安装) + + + +### 一、结构表系统 (Struct Sheet System) + +**个人结构表** + +`JustEnoughVCS` 允许每名成员都建立自己的 **结构表**，它是 **该成员对于自己可见文件的理解**，它不会也不需要被其他成员知道长什么样。每名成员都在自己的 **结构表** 内工作，在需要的时候将部分 **文件可见性** 分享给他人即可。 + +**参考结构表** + +在 `JustEnoughVCS` 的上游仓库（Upstream Vault）中，会由 **仓库管理员** 维护一份公开可见的 **参考结构表** (Reference Sheet)，所有成员都可以查询到 **文件在参考结构表中的位置**，以方便建立对文件的理解。 + +

+ + JustEnoughVCS + +

+ 参考结构表用于锚定文件的权威命名 +

+

+ + + +### 二、串行编辑 + +`JustEnoughVCS` 采用 **串行编辑模型**，从根本上消除合并冲突。我们的权限原则是：**可见即可读，持有则可写**。 + +当您持有文件时，您拥有独占的编辑权。其他成员可以看到当前版本，但无法同时编辑。编辑完成后，您提交的新版本立即可供所有人获取。 +串行编辑确保只有一个“真相来源”。如果有成员在未持有权限或基于过时版本进行编辑，系统会明确标记这些修改为**无效编辑**，也就是说，它们不会被意外提交或覆盖有效版本。 +不过不用担心，在 `JustEnoughVCS` 的前端（[命令行、桌面端](#安装)）中，提供了清晰可见视图，用于确认文件状态。 -## 多文件结构 -它鼓励用户以习惯的方式去放置、管理自己的资产，并按需将文件的 **可见性** 分享给团队内的其他成员。正因每位成员都有自己的结构，也不必担心文件的移动会影响他人。 +### 三、架构 +`JustEnoughVCS` 为集中式版本控制，分为 **服务端** 和 **客户端**，本地工作区仅为用于记录修改和更新的文件拷贝。 -## 串行编辑 +**上游库 (Upstream Vault)** -同时，`JustEnoughVCS` 以文件为粒度进行权限管理，在同一时刻内，只有一名成员持有该文件，即拥有文件的 **编辑权**。在更新文件版本后，其他成员可在下次状态检查时发现新版本，并决定是否将最新版本更新到本地。 +上游库记录了如下信息： +1. 上游库配置信息 +2. 成员注册信息及公钥 +3. 结构表 + 1. 当前持有者 + 2. 映射关系 +4. 文件元数据 + 1. 当前持有者 + 2. 版本顺序 +5. 文件历史版本存储**（全量、未压缩）** -## 拒绝模糊映射 -在实际文件结构与记录的文件结构有 **偏差** 时，`JustEnoughVCS` 将会禁止您追踪文件的版本，您需要解释清楚您本地的结构变动才能继续。 +**工作区 (Local Workspace)** + +工作区记录了如下信息： + +1. 工作区配置信息 +2. 上游库元数据的本地缓存 +3. 结构表的本地缓存：用来对比本地和上游差异 +4. 本地结构表：用来分析工作区变化 +5. 物理文件 + +

+ + JustEnoughVCS + +

+ Vault 和 Workspace 的关系 +

+

+ + + +## 安装 + +该仓库为 `JustEnoughVCS` 的核心库，不提供任何交互功能。 + +请前往对应的仓库以下载或构建 `JustEnoughVCS` 的前端： + +- [命令行前端](https://github.com/JustEnoughVCS/CommandLine) +- [桌面端](https://github.com/JustEnoughVCS/Desktop) **开发中** ## 路线图 -### 核心库 +- [ ] 核心功能 -- [ ] 增量的文件更新和存储 -- [ ] 多参照表 + - [x] 表管理 + - [x] 追踪 + - [x] 对齐 + - [x] 分享 + - [x] 参考 + - [x] 管理员工具 + - [ ] 版本跳转 + - [ ] 版本冻结 + - [ ] 借用器 +- [ ] 命令行 + - [ ] 完整核心功能封装 -### 拓展工具 + - [x] 帮助 + - [x] 补全 + - [ ] 内嵌文档 + - [ ] JSON 输出 + +- [ ] 桌面端 + + - [ ] 完整核心功能封装 + + - [x] 命令行包装器 + - [ ] 主题 + +- [ ] 2026 计划 + + - [ ] 桌面端支持 **当前阶段** + + - [ ] 规范化核心、命令行代码 + - [ ] 提高异步、并发支持 + - [ ] 存储优化 + - [ ] 分布式内容存储、集中式权限管理 -- [x] 命令行客户端 -> [CommandLine](https://github.com/JustEnoughVCS/CommandLine ) -- [ ] 桌面客户端 -> [JVDesktop](https://github.com/JustEnoughVCS/JVDesktop ) -- [ ] 声明式资产管理 -> [JVRefs](https://github.com/JustEnoughVCS/AssetsConfig) (目前 Private) -- [ ] 文件合并器 -> [JVBinMerger](https://github.com/JustEnoughVCS/BinMerger) (目前 Private) @@ -84,8 +177,18 @@ 本项目采用 **MIT 许可证**。 -有关完整的许可证条款，请参阅项目根目录中的 ./LICENSE-MIT.md 文件。 +有关完整的许可证条款，请参阅项目根目录中的 *./LICENSE-MIT.md* 文件。 --- 最后，感谢您对 `JustEnoughVCS` 的关注！ + + + +## 一些碎语 + +> 为什么要给它命名 `JustEnoughVCS` ？ +> +> 如果你认为它听起来像是 Minecraft 中的 Mod 才会取的名字，那你就猜对了！ +> +> 其实灵感正是来自 `JustEnoughItems` 😄 diff --git a/docs/Resources/Visual/Image1.png b/docs/Resources/Visual/Image1.png new file mode 100644 index 0000000..d3faeb5 Binary files /dev/null and b/docs/Resources/Visual/Image1.png differ diff --git a/docs/Resources/Visual/Image2.png b/docs/Resources/Visual/Image2.png new file mode 100644 index 0000000..3dd4892 Binary files /dev/null and b/docs/Resources/Visual/Image2.png differ diff --git a/docs/Resources/Visual/Yizi_Icon.png b/docs/Resources/Visual/Yizi_Icon.png new file mode 100644 index 0000000..5c9f3d1 Binary files /dev/null and b/docs/Resources/Visual/Yizi_Icon.png differ diff --git a/docs/Resources/Visual/background.png b/docs/Resources/Visual/background.png new file mode 100644 index 0000000..feebec5 Binary files /dev/null and b/docs/Resources/Visual/background.png differ diff --git a/docs/images/Background.png b/docs/images/Background.png deleted file mode 100644 index 61e5d7b..0000000 Binary files a/docs/images/Background.png and /dev/null differ diff --git a/docs/images/Header.png b/docs/images/Header.png deleted file mode 100644 index 545bafb..0000000 Binary files a/docs/images/Header.png and /dev/null differ diff --git a/docs/images/Header_Large.png b/docs/images/Header_Large.png deleted file mode 100644 index a84018f..0000000 Binary files a/docs/images/Header_Large.png and /dev/null differ diff --git a/docs/images/Yizi.png b/docs/images/Yizi.png deleted file mode 100644 index 48e8399..0000000 Binary files a/docs/images/Yizi.png and /dev/null differ diff --git a/docs/images/Yizi_Large.png b/docs/images/Yizi_Large.png deleted file mode 100644 index c82c320..0000000 Binary files a/docs/images/Yizi_Large.png and /dev/null differ -- cgit