diff --git a/BRANCHES.md b/BRANCHES.md new file mode 100644 index 0000000..0ff6ea7 --- /dev/null +++ b/BRANCHES.md @@ -0,0 +1,20 @@ +# Branch file format + +Branches are stored in a binary format that stores a list of objects in that branch along with the branch it came from(if any). Numbers are in little-endian unless otherwise noted. The entries should be ordered chronologically with earlier first. + +``` +0xB7ACF11E: Magic number +0x00000000: 32-bit version. By convention, unofficial branch formats should have the left-most(commonly referred to as the 31st bit) set. +0x0000000000000007: 64-bit number of entries +0x0000000067D9F6C9: 64-bit unix timestamp of the branch's creation in seconds +0xEAE1168D9B0245679DFC6DB5E8949C03: The branch's UUID. MUST be cryptographically random! + +(entries) +``` + +Each entry is a reference to an object in the format: + +``` +0x182E06194DB125D7: 64-bit unix timestamp(in nanoseconds) of the object's creation +0xCF83E1357EEFB8BD: The SHA512 hash of the object truncated to 64 bits +``` \ No newline at end of file diff --git a/MODS.md b/MODS.md new file mode 100644 index 0000000..56b398d --- /dev/null +++ b/MODS.md @@ -0,0 +1,39 @@ +# Mod file format + +Mod files are the exception where they are a text-based format. They operate on a series of tags, similar to the format of email: + +``` +Short-Message: Added documentation +Author: Arthur Beck +SHA512-Hash: CF83E1357EEFB8BDF1542850D66D8007D620E4050B5715DC83F4A921D36CE9CE47D0D13C5D85F2B0FF8318D2877EEC2F63B931BD47417A81A538327AF927DA3E +Type: Addition+Documentation +GPG-Sig: (insert base64 encoded GPG signature here) +Branch: main +Objects: cf83e1357eefb8bd182e06194db125d7 +Timestamp: 2025-03-18 18:52:49-05:00 +--BEGIN BODY-- +This mod adds documentation for mods, branches, and objects. +--END BODY-- +``` + +The format consists of any number of tags and a body, separated by `--BEGIN BODY--` on it's own line. The file is terminated by `--END BODY--` on it's own line. The body can contain any valid UTF-8 except for the end body string. The list of available tags are: + +- `Objects`: Mandatory. Lists the objects in the mod. +- `Author`: Also mandatory. Must list at least the name and email of the author. These may be redacted. Additional fields may be specified as author tags: + - `<(email)>`: Email tag. + - ``: Bluesky tag. + - ``: Mastodon tag. + - ``: Alternate author tag. + - `<(website)>`: Website tag. +- `Branch`: Mandatory. The branch name that the mod is made on. +- `Timestamp`: Mandatory. The creation time of the mod in RFC3339 format with a precision of seconds. +- `Type`: Optional but recommended. Contains tags(any UTF-8 string containing characters that match the regex `[0-9a-zA-Z-_]`) for what the mod does separated by `+`s. A list of suggested tags is: + - `Addition`: This mod adds something + - `Removal`: This mod removes something + - `Bugfix`: This mod fixes a bug + - `Documentation`: This mod changes documentation + - `Features`: This mod changes features + - `License`: This mod changes something about licensing +- `Short-Message`: Optional but recommended. Contains a short message containing any UTF-8 characters except for newline characters. +- `SHA512-Hash`: Optional. Hash of the mod file itself. +- `GPG-Sig`: Optional but highly recommended. Base-64 encoded GPG signature of the objects. Same order as the `Objects` tag. \ No newline at end of file diff --git a/OBJECTS.md b/OBJECTS.md index 1f65211..6dfe311 100644 --- a/OBJECTS.md +++ b/OBJECTS.md @@ -4,13 +4,18 @@ Objects are stored for each mod. Each object consists of a custom binary diff-st ``` 0x0B7D1FF0: Magic number -0x00000000: 32-bit version. By convention, unofficial object formats should have the left-most(commonly referred to as the 31st bit) set. +0x00000001: 32-bit version. By convention, unofficial object formats should have the left-most(commonly referred to as the 31st bit) set. 0x0000000000000007: 64-bit number of entries +0x0000000067D9F179: 64-bit unix timestamp of the mod's creation in seconds +0x182E06194DB125D7: 64-bit unix timestamp(in nanoseconds) of the object's creation +0x0000000000000000: 64-bit unix timestamp(in nanoseconds) of the previous object's creation or 0 if no there is no previous object -0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000: Padding +0x000000000000000000000000000000000000000000000000: Padding 0xCF83E1357EEFB8BDF1542850D66D8007D620E4050B5715DC83F4A921D36CE9CE47D0D13C5D85F2B0FF8318D2877EEC2F63B931BD47417A81A538327AF927DA3E: SHA512 hash of object with hash replaced with this hash(the SHA512 hash of an empty string) +0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000: Same as hash above but of previous object, or 0 if no previous object. + (entries) ``` @@ -40,4 +45,5 @@ Known versions: |32-bit value|Name| |-----|-----| -|0x00000000|Official venus version 0.1(this doc)| +|0x00000000|Version from before version 0.1| +|0x00000001|Official venus version 0.1(this doc)| diff --git a/README.md b/README.md index 4185e02..246fcbd 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,16 @@ -# venus +# Venus -the VCS built to be fast \ No newline at end of file +Venus is a work-in-progress VCS built to be fast and efficient. Tired of waiting ages for Git to "resolve deltas"(a process vital to the way git works)? Use Venus(when it's functional, of course)! + +## Glossary +mod: Equivalent to commits in other VCS'. +object: A file storing differences from the previous mod. + +## .venus structure + +.venus/objects: Object files(specified in [OBJECTS.md](./OBJECTS.md)) with the extension of `.venus-object`. They are named after the SHA512 hash stored in the object truncated to 16 characters and then the hexadecimal unix timestamp in nanoseconds of the object's creation. For example, `cf83e1357eefb8bd182e06194db125d7.venus-object` would be an object file with completely empty content created on Tuesday, March 18, 2025 at 10:26:52 PM GMT. This string of hexadecimal characters is also used to identify the mod. +.venus/branches: Branch files(specified in [BRANCHES.md](./BRANCHES.md)) with the extension of `.venus-branch`. They are named after the branch name(i.e. `main.venus-branch`), meaning that branch names have to be unique. +.venus/mods: Mods files(specified in [MODS.md](./MODS.md)) with the extension of `.venus-mod`. They are named with the SHA512 hash of them truncated to 16 characters and concatenated to the unix timestamp in hex of their creation date. +.venus/mods/NEW_MOD.venus-mod: A file similar to git's `COMMIT_MSG` file. Staging file while the user is creating a new mod. +.venus/active/BRANCH: A file containing only the active branch name. +.venus/active/MOD: A file containing only the active module of the module file name without the extension. \ No newline at end of file