EmbeddingVC

Git-inspired version control for embedding collections. Implemented commands: init, config, add, status, embed, commit, branch, log, diff, and checkout, using Python 3.11+.

Requirements

• Python 3.11 or newer
• Git

Document staging uses PyYAML and PyMuPDF. Embedding generation optionally uses Sentence Transformers. Installing in a virtual environment keeps each contributor's machine isolated and reproducible.

Install for development

Clone the repository, enter it, and create a virtual environment.

git clone <github-repository-url>
cd embeddingVC
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .

The -e editable installation means local source-code changes take effect without reinstalling the package. Verify the installation:

.\.venv\Scripts\embeddingvc.exe --version
.\.venv\Scripts\embeddingvc.exe --help

On macOS or Linux, use:

python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/embeddingvc --help

Initialize an existing folder

EmbeddingVC is installed inside this project's .venv, so a newly opened terminal may report that embeddingvc is not recognized until the environment is activated.

For example, to initialize an existing folder named New folder using Windows Command Prompt:

cd "C:\Users\Adwait Tagalpallewar\Desktop\New folder"
"C:\Users\Adwait Tagalpallewar\Desktop\embeddingVC\.venv\Scripts\embeddingvc.exe" init

This uses the full executable path and does not require activation. Alternatively, activate the environment once in the current Command Prompt window:

"C:\Users\Adwait Tagalpallewar\Desktop\embeddingVC\.venv\Scripts\activate.bat"
cd "C:\Users\Adwait Tagalpallewar\Desktop\New folder"
embeddingvc init

For PowerShell, activate it with:

& "C:\Users\Adwait Tagalpallewar\Desktop\embeddingVC\.venv\Scripts\Activate.ps1"
Set-Location "C:\Users\Adwait Tagalpallewar\Desktop\New folder"
embeddingvc init

Activation applies only to the current terminal session. In a new terminal, activate the environment again or use the full path to embeddingvc.exe.

You can also remain in any directory and pass the destination explicitly:

"C:\Users\Adwait Tagalpallewar\Desktop\embeddingVC\.venv\Scripts\embeddingvc.exe" init "C:\Users\Adwait Tagalpallewar\Desktop\New folder"

Initialization keeps existing documents and unrelated files. If the destination already has README.md or embeddingvc.yaml, the command stops unless --force is supplied. An existing .embeddingvc directory always prevents reinitialization.

Try the init command safely

Create a disposable project outside the source repository. From the embeddingVC directory on PowerShell:

$testDirectory = Join-Path $env:TEMP "embeddingvc-manual-test"
New-Item -ItemType Directory -Path $testDirectory -Force | Out-Null
Set-Location $testDirectory
& "<path-to-embeddingVC>\.venv\Scripts\embeddingvc.exe" init student-notes
Get-ChildItem -Force .\student-notes
Get-Content .\student-notes\.embeddingvc\HEAD
Get-Content .\student-notes\.embeddingvc\index.json

Replace <path-to-embeddingVC> with the absolute path where you cloned this repository. A successful run creates student-notes and prints the next steps. Its HEAD should contain ref: refs/heads/main, and index.json should contain an empty documents object.

Run the same command a second time to test overwrite protection:

& "<path-to-embeddingVC>\.venv\Scripts\embeddingvc.exe" init student-notes

The second run should exit with an error stating that the repository is already initialized. Do not use an important existing directory for manual tests.

Use embeddingvc init for the current directory. embeddingvc init <directory> --force replaces an existing README and config but always refuses existing .embeddingvc metadata. Existing documents and Git ignore rules are preserved. Linked managed paths are rejected.

Initialization creates data/, output/chroma/, configuration, instructions, and .embeddingvc/ with objects, commits, refs, cache, HEAD and an empty index. HEAD points to refs/heads/main; the empty main reference means no commit yet. The index starts as {"version": 1, "documents": {}}.

The config leaves the model revision unset; pin an immutable model commit before embedding generation. Use checkout to restore a snapshot or repair HEAD synchronization. See history and diff for snapshot inspection. No models or database packages are installed by init.

Generate embeddings

Install the embedding dependencies once from the source checkout:

.\.venv\Scripts\python.exe -m pip install -e ".[embeddings]"

In an initialized collection, pin the model's full 40-character commit SHA, track your source directory, and prepare the candidate:

embeddingvc config set model_revision <exact-model-commit>
embeddingvc add data
embeddingvc embed
embeddingvc status

embed refreshes every tracked root, including edits, new supported files and deletions. Identical compatible chunks share one immutable embedding object; an unchanged second run makes zero encoder calls. It verifies stored objects and model dimensions, then rechecks sources and configuration before atomically publishing the index. Failed runs preserve the previous index and retain valid objects for retry. It does not create a commit or modify the active database.

The model's pooling is used by default. Optional embedding.pooling and embedding.dimension settings select a pooling mode and expected dimension. Model weights use the normal library cache. See the embed guide for the storage contract and opt-in real-model test.

Commit an embedded snapshot

.\.venv\Scripts\python.exe -m pip install -e ".[vector-store]"
embeddingvc commit -m "Initial knowledge-base embeddings"

Commit saves a complete immutable snapshot and synchronizes Chroma from stored vectors. It rejects stale candidates and unchanged snapshots. If synchronization fails after publication, rerun commit to repair the existing snapshot without creating another one. See the commit guide for recovery and the shared checkout integration contract.

Create and list branches

After the first commit, list local branches or create an experiment branch from the current or an explicit commit:

embeddingvc branch
embeddingvc branch minilm-experiment
embeddingvc branch minilm-experiment <start-commit>

Branch creation only writes .embeddingvc/refs/heads/<name> and prints the checkout command. It does not switch HEAD, copy vectors, or modify Chroma.

Handled filesystem failures restore overwritten files and remove newly created files and empty directories. This is not crash recovery; do not run simultaneous initializers or edit managed files during initialization.

Tests

Run the automated test suite before pushing changes:

.\.venv\Scripts\python.exe -m unittest discover -s tests -v

macOS and Linux:

.venv/bin/python -m unittest discover -s tests -v

The suite covers initialization, config, branches, staging, status and embedding generation, including reuse, stale settings, corruption and atomic failures. Embedding unit tests use a deterministic fake encoder without downloading models. Real-model integration is opt-in; see the embed guide.

Team workflow

The repository owner should create an empty GitHub repository without adding a README, license, or .gitignore, because those files already exist locally. Then connect and push this checkout:

git branch -M main
git remote add origin <github-repository-url>
git push -u origin main

Add the other three contributors under the GitHub repository's collaborator or team settings. Each contributor follows the installation steps above.

For each task, create a short-lived branch from the latest main:

git switch main
git pull --ff-only
git switch -c feature/status-command

After making changes, run the tests and push the branch:

.\.venv\Scripts\python.exe -m unittest discover -s tests -v
git status
git add <changed-files>
git commit -m "Add status command"
git push -u origin feature/status-command

Open a pull request on GitHub and have at least one teammate review it before merging. Avoid having multiple people implement the same module simultaneously; split work by feature and coordinate shared changes to cli.py, repository formats, and configuration schemas.

Never commit .venv/, generated output/ data, .embeddingvc/ object data, credentials, or downloaded embedding models. The project .gitignore already excludes local build and virtual-environment files.