arc/docs/spec.md

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:

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.