{"id":23989606,"url":"https://github.com/candidtim/fvcs","last_synced_at":"2025-11-19T04:05:08.002Z","repository":{"id":227900721,"uuid":"737812376","full_name":"candidtim/fvcs","owner":"candidtim","description":"File-based Version Control System (experiment)","archived":false,"fork":false,"pushed_at":"2024-01-01T15:40:00.000Z","size":52,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-25T03:42:35.815Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/candidtim.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-01-01T15:39:19.000Z","updated_at":"2024-01-01T15:39:59.000Z","dependencies_parsed_at":"2024-03-15T18:14:52.787Z","dependency_job_id":"639b021a-89fa-4a13-b49e-caed3b14c88a","html_url":"https://github.com/candidtim/fvcs","commit_stats":null,"previous_names":["candidtim/fvcs"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/candidtim/fvcs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/candidtim%2Ffvcs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/candidtim%2Ffvcs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/candidtim%2Ffvcs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/candidtim%2Ffvcs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/candidtim","download_url":"https://codeload.github.com/candidtim/fvcs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/candidtim%2Ffvcs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":285181687,"owners_count":27128334,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-19T02:00:05.673Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-07T17:32:18.773Z","updated_at":"2025-11-19T04:05:07.986Z","avatar_url":"https://github.com/candidtim.png","language":"Python","readme":"# FVCS\n\nAn experimental file-centric version control system (every file has its own\nversion history).\n\n## Goals. Expected features.\n\nGoals:\n\n - evaluate the usability of a file-centric version control in modern software\n   development environment\n - have fun reimplementing what SCSS did several decades ago\n\nExpected features:\n\n - **file-centric**: every file has its own version history (as opposed to\n   repository-based VCS: Git, Mercurial, or Subversion, for instance)\n - **local data model**: local repository is self-contained, including all data\n   and history\n - ~~**distributed data model**: to be built on top of a local data model, can\n   be added later on~~\n - **minimalistic** and **ejectable**: based on existing tools (e.g., `diff`),\n   data and history can be accessed, extracted and even modified (corrected)\n   directly in the file system using commonly-available command-line tools\n\nStatus: in progress, experimental, some features may be not available\n\n## Advantages and disadvantages of file-centric version control\n\n**Advantages**:\n\n - Isolation and independence: changes to one file do not affect the versioning\n   or history of other files; allows to work on different files without\n   interference.\n - Fine-grained version control: useful when different files in a project have\n   different lifecycles or when you want to manage changes to specific files\n   separately.\n - Simplicity: file-centric model is easier to understand.\n - Flexibility: theoretically, repository-centric versioning is a superset of a\n   file-centric versioning; latter ultimately should allow more flexible usage\n   workflows\n\n**Disadvantages**:\n\nThe objective of this project is to overcome many of the disadvantages that are\ninherent to the file-centric model. Most of the disadvantages are related to\nthe difficulty to manage the following scenarios:\n\n - Complex development workflows (branching, merging, etc.)\n - Distributed and collaborative workflows\n - Handling the entire source tree as a cohesive unit\n\n**Suitability**:\n\nFile-centric VCS is expected to be most suitable for projects where high degree\nof isolation between distinct files is necessary, or already exists. For\nexample: version control of a set of distinct scripts, version control of user\ndotfiles, etc.\n\n## Design\n\nThis implementation being experimental, it is important to be able to:\n\n - avoid irrecoverable data and history corruptions\n - extract data and history in all situations\n   - ideally, even eject into a traditional VCS: Git, for example\n - confidently fix errors directly in the internal data model\n\nFor these reasons, the design choices are minimalist and based on reusability\nof existing and well-known tools (e.g., use `diff` and `patch` instead of\nimplementing own diff algorithms).\n\n## Usage\n\n    # initialize a repository\n    fv init\n\n    # add a file\n    echo \"Hello, World!\\n\" \u003e README.txt\n    fv add README.txt --comment \"Created the README\"\n\n    # modify a file\n    echo \"Hello, FVCS!\\n\" \u003e\u003e README.txt\n    fv diff README.txt\n    fv update README.txt -c \"Updated the README\"\n\n    # add another file, modify it several times\n    echo \"foo\\n\" \u003e foo.txt\n    fv add foo.txt -c \"foo\"\n    echo \"bar\\n\" \u003e\u003e foo.txt\n    fv update foo.txt -c \"bar\"\n    echo \"baz\\n\" \u003e\u003e foo.txt\n    fv update foo.txt -c \"baz\"\n\n    # snapshot across all files in a repository:\n    fv snapshot SNAPSHOT_NAME -c \"First snapshot\"\n\n    # update several files at once (each change is recorded separately)\n    echo \"Hello, fine-grained version control\" \u003e\u003e README.txt\n    echo \"qux\" \u003e\u003e foo.txt\n    fv update *.txt -c \"Updated all text files\"\n\n    # show single files history:\n    fv hist README.txt\n    fv hist foo.txt\n\n    # get a specific file version\n    fv get README.txt --version 1\n    fv get README.txt --snapshot SNAPSHOT_NAME\n\n    # restore an entire repository to a snapshot\n    fv restore SNAPSHOT_NAME\n\n    # create a file version that removes it\n    fv rm README.txt -c \"Delete the README\"  # doesn't delete its history\n\n    # remove the file and its history (forget it)\n    fv purge README.txt  # deletes the file and its history\n\n    # eject, use snapshots as repository versions (implies current latest too)\n    fv eject --snapshots\n    # eject, interpret every change as a repository version\n    # (uses update timestamps to order the changes)\n    fv eject --file-versions\n\n## Data and history storage format\n\nAll data and history is stored in a \".fvcs\" directory in the root of a\nrepository:\n\n - `.fvcs/tree`: files and diffs (history)\n   Every file in the repository has an according direcotory under `.fvcs/tree`\n   with the same relative path; this directory stores all diffs of a file. Any\n   file version can be restored by rolling up all diffs (patching) up to a\n   target version.\n - `.fvcs/snapshots`: snapshot data\n   Every snapshot is a TOML file with references to repository files and their\n   versions. Files that didn't exist in the repository by the time the snapshot\n   was created are naturally not listed.\n\n## Random ideas\n\n - Evaluate a possibility to inter-operate with Git, reuse Git for distributed\n   workflows, or even complex local workflows. Evaluate a possibility to use\n   FVCS *within* a Git repository.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcandidtim%2Ffvcs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcandidtim%2Ffvcs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcandidtim%2Ffvcs/lists"}