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 +++++++++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 130 insertions(+), 35 deletions(-) (limited to 'README.md') 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` 😄 -- cgit