hanna
a6b1a027c8
- Replace rmp-serde with bincode 1.x in Cargo.toml - Update store.rs serialization/deserialization and ID hashing - Rename model.rs helpers from to_msgpack/from_msgpack to to_bytes/from_bytes - Consolidate MsgPack/MsgPackDecode error variants into single Bincode variant - Remove skip_serializing_if on ssh_signature (incompatible with bincode) - Update all documentation to reflect bincode storage format
129 lines
6.9 KiB
Markdown
129 lines
6.9 KiB
Markdown
# Arc Implementation Plan
|
|
|
|
This is the implementation plan to implement the 'arc' version control system.
|
|
This plan follows a phased implementation, with each phase focusing on a specific part.
|
|
|
|
## Implementation Overview
|
|
|
|
This is an overview of the foundational rules that make the software.
|
|
|
|
1. Arc should be written from the ground up, with very little reliance on git.
|
|
2. Arc should be written in the latest version of the Rust toolchain for stability.
|
|
3. The development enviroment should use a nix flake with direnv for easy setup.
|
|
3a. The flake should use `nixpkgs-unstable`, `flake-parts`, `fenix`, and `crane`.
|
|
3b. Building the project should be done **purely** through `nix build` and nothing else.
|
|
4. Rather than being snapshot based like Git, Arc should be based on incremental deltas.
|
|
5. Rather than having to manually stage changes, changes should be automatically tracked.
|
|
6. The command line interface (CLI) should be ergonomic and easy to understand and use.
|
|
7. All implemented functionality should have tests written in a file in the `tests/` directory.
|
|
8. After every substantial change, the changes should be committed using conventional commits format.
|
|
8a. use `feat: <message>` for new features, `fix: <message>` for bug fixes, `refactor: <message>` for changes.
|
|
8b. use `docs: <message>` for docs changes, `build: <message>` for build system changes, etc.
|
|
9. Anything involving remotes should use `libgit` or `git2` libraries for compatibility.
|
|
10. Deltas should be stored using ZSTD compressed bincode files for easy storage.
|
|
11. When pushing, pulling, and fetching from remotes, it should be bridged to git.
|
|
12. Lastly, it should cover 90% of use cases that git has, for full feature support.
|
|
13. Arc should support **optional** commit signing via SSH keys.
|
|
14. Arc uses a bookmark system instead of a branch system.
|
|
15. Previous commits are immutable and can not be edited.
|
|
16. Migrating and cloning should preserve commit history.
|
|
17. Ignore file name should be `.ignore` or `.arcignore`.
|
|
18. Config and data files should use the YAML format.
|
|
19. Bookmarks should be treated as branches when pushed to git.
|
|
20. Tags should be treated as normal git tags when pushed to git.
|
|
21. Use local config values first, then fallback to global.
|
|
22. Default bookmark is `main`, default remote is `origin`.
|
|
23. Aliases defined in config should be expanded at the CLI level before dispatch.
|
|
24. Tags are immutable.
|
|
|
|
In order for an implementation phase to be successful, the following has to be met:
|
|
|
|
1. All tests defined in the `tests/` folder must succeed via `nix develop -c cargo test`
|
|
2. Clippy must produce no errors or warnings running via `nix develop -c cargo clippy`
|
|
3. Formatting must be consistent and produce no errors with `nix develop -c cargo fmt`
|
|
4. The project must successfully build via `nix build`, `cargo build` is not an option
|
|
5. As a final measure, the implemented functionality must be thorougly evaluated
|
|
|
|
## Command Overview
|
|
|
|
This is an overview of all the commands that will be implemented:
|
|
|
|
Any arguments wrapped in `[]` are considered optional.
|
|
Any arguments wrapped in `<>` are considered required.
|
|
Ranges `start..end` are inclusive and have optional start and end.
|
|
|
|
- `arc init [path]` - initialize a new arc repository
|
|
- `arc commit <message>` - commit the changes in the worktree
|
|
- `arc log [start..end]` - show a log of previous commits (or last commit)
|
|
- `arc status` - show the current changes since last commit
|
|
- `arc diff [start..end]` - show a diff of changes (or last commit)
|
|
- `arc switch <mark|tag>` - switch the worktree to a bookmark or tag
|
|
- `arc merge <mark|tag>` - merge changes from a bookmark or tag into the worktree
|
|
- `arc show <mark|tag|commit>` - show the details of a bookmark, tag, or commit
|
|
- `arc history <file> [start..end]` - show who last modified each line of a file in a range (or last commit)
|
|
- `arc revert <commit|start..end>` - create a commit to revert the changes in a range or commit
|
|
- `arc reset [file...]` - clean the worktree and reset all current changes to the previous commit
|
|
- `arc push [-r remote]` - push commits to a git remote using the git bridge
|
|
- `arc pull [-r remote]` - pull changes from a git remote using the git bridge
|
|
- `arc clone [-b branch] <url> [path]` - clone a git remote and convert it to a arc repo
|
|
- `arc migrate` - convert a git repo in the CWD to an arc repo
|
|
- `arc help` - show a help message of commands using clap
|
|
- `arc mark add <name> [commit]` - set a bookmark at the specified commit
|
|
- `arc mark rm <name>` - remove a bookmark from the repo
|
|
- `arc mark list` - list all bookmarks in the repo
|
|
- `arc mark rename <name> <new>` - rename a bookmark to a new name
|
|
- `arc tag add <name> [commit]` - set a tag at the specified commit
|
|
- `arc tag rm <name>` - remove a tag from the repo
|
|
- `arc tag list` - list all tags in the repo
|
|
- `arc stash create <name>` - create a named stash
|
|
- `arc stash use <name>` - switch to a named stash
|
|
- `arc stash push` - push changes to the current stash
|
|
- `arc stash pop` - pop changes from the current stash
|
|
- `arc stash rm <name>` - remove a named stash
|
|
- `arc stash list` - list the named stashes
|
|
- `arc graft <start..end|commit> <--onto bookmark|commit>` - cherrypick (rebase) commit(s) into a bookmark
|
|
- `arc config set [-g] <key> <value>` - set a config value in the repo or global config
|
|
- `arc config get [-g] <key>` - get a config value in the repo or global config
|
|
- `arc config show [-g]` - show the current configuration values
|
|
- `arc config unset [-g] <key>` - unset a value and remove it from the config
|
|
- `arc sync [-p]` - sync branches (bookmarks) and tags locally (and optionally push local ones remotely)
|
|
- `arc remote add <name> <url>` - add a remote to the repository
|
|
- `arc remote rm <name>` - remove a remote to the repository
|
|
- `arc remote list` - list the remotes in the repository
|
|
|
|
## Config Format
|
|
|
|
This is an example configuration format to build on:
|
|
|
|
```yml
|
|
user:
|
|
name: hanna
|
|
email: me@hanna.lol
|
|
key: ~/.ssh/id_ed25519
|
|
|
|
default:
|
|
bookmark: main
|
|
remote: origin
|
|
|
|
aliases:
|
|
c: commit
|
|
p: push
|
|
l: pull
|
|
```
|
|
|
|
## Implementation Phases
|
|
|
|
These are the implementation phases that should be implemented incrementally.
|
|
|
|
1. **Project scaffolding** - Nix flake, direnv, Rust project structure, CLI skeleton with clap, help
|
|
2. **Core repo structure** - init, internal data model (commits, deltas, YAML config), .arcignore
|
|
3. **Tracking & committing** - commit, status, diff, auto-change detection, ZSTD + bincode storage
|
|
4. **History & inspection** - log, show, history, state reconstruction from delta chains
|
|
5. **Bookmarks & tags** - mark commands, tag commands, and switch command
|
|
6. **Undo & modification** - revert, reset, graft, three-way merge
|
|
7. **Stash system** - stash commands
|
|
8. **Config system** - config commands, resolution (rule 21)
|
|
9. **Git bridge & remotes** - remote, push, pull, clone, migrate, and sync commands, git2 integration
|
|
10. **Commit signing** - Optional SSH key signing (rule 13)
|
|
|
|
Once all phases have been completed, and conditions pass, the software is finished.
|