Try Kin alongside Git.

Before you start

• A Git repository you can afford to experiment on. Use a copy: this page is an evaluation path, not a migration plan.
• Kin on your PATH, and a shell at the root of that repository.
• Disk for a second store beside .git. kin status reports the store size and how it compares to the Git object store, and that ratio varies widely between repositories.
• A language Kin has an adapter for, if you want semantic answers. Files in other languages are admitted with their content and history and produce no entities.

The steps

1. 01

   Admit the repository

   Admission reads the Git repository and builds graph-owned authority from it. It does not rewrite the Git repository, and it does not ask you to stop using it.

   kin init .

   Copy command

   Compare with the saved example output

     [ 4/17] plan semantic import 4 files, 1 commits | 0.0s
     [ 7/17] prove Git source re-deriving 1 commits | 0.0s
     [ 9/17] copy Git objects 0/7 objects | 0.0s
   Initialized Kin repository authority at /private/tmp/docsverify-workflows/kin-orders/.kin
     Imported: exact reachable Git history, refs, raw objects, workspace, and admission policy

   A file and commit count in the import plan, then a line naming what came in: reachable history, refs, raw objects, the workspace and the admission policy. Unreachable Git objects are not part of that set. Larger repositories take proportionally longer, and the run reports each phase as it goes.

2. 02

   See where each change came from

   Kin keeps the origin of every change, so an imported commit and a change Kin recorded are never confused for each other.

   kin log

   Copy command

   Compare with the saved example output

   change 5c15d027b9849974ea2b4d8e31ce8ce11ca3428d9bce65bac7d2d3a96fffd855
   Origin: native
   Parents: 61ad778d54790180e31c78b2f1b6f8912d61fa0eb22eb049f70af07a46d8d865
   
   change 61ad778d54790180e31c78b2f1b6f8912d61fa0eb22eb049f70af07a46d8d865
   Origin: git commit 3fcc18849eea798f823e07a128900c9e6ef170df

   Origin: git commit <sha> on everything that came in with the import, and Origin: native on everything Kin recorded afterwards. The excerpt above drops the author, date and delta lines each change also carries.

3. 03

   Record a change in Kin, and watch Git stay where it was

   This is the part worth understanding before you evaluate anything else. Kin recording a change does not move Git.

   kin commit -m "Accept a currency argument when formatting an amount"
   git status --short --branch
   git log --oneline

   Copy command

   Compare with the saved example output

   Created semantic change 5c15d027b9849974ea2b4d8e31ce8ce11ca3428d9bce65bac7d2d3a96fffd855 on branch 'refs/heads/main' (2 entities, 55 relations, 1 artifacts)
   
   ## main
    M src/money.js
   
   3fcc188 Add order pricing and receipt rendering

   Kin has two changes; Git has one commit and a modified file. Both are true at once, and neither tool has been lied to. If you want Git moved, commit with Git as well, or export.

4. 04

   Hand the work back to Git

   Export writes a new Git repository from Kin authority. It is how you check that nothing is trapped, and it is worth running once during an evaluation rather than taking on trust.

   kin git export --output /tmp/docsverify-workflows/exported
   git -C /tmp/docsverify-workflows/exported log --oneline

   Copy command

   Compare with the saved example output

   Exported repository 1a21f89c-9c02-488f-ab48-ac2d837da11b authority generation 4 to /private/tmp/docsverify-workflows/exported
   1 imported commits reused, 1 native commits written, 1 refs written
   
   670e425 Accept a currency argument when formatting an amount
   3fcc188 Add order pricing and receipt rendering

   A Git repository with both changes as commits. The commit that came in from Git keeps its original sha, 3fcc188 here, and the change Kin recorded is written as a new commit. The path above is the one this run used; yours only has to be outside the Kin working repository.

5. 05

   Read the boundary before you plan anything

   Kin says which command surfaces are ready rather than leaving you to find out. Read this before you decide how far to take an evaluation. The excerpt below drops most of the thirty-five rows.

   kin capabilities

   Copy command

   Compare with the saved example output

   Kin repository-v6 command capabilities
   Bounded dogfood ready: yes (12/12)
   All declared command surfaces enabled: yes (35/35)
   Fully general Git replacement ready: no (34/35 general)
   
   READY  git export          required
   READY  clone
   READY  migrate
   READY  push
   READY  pull
   READY  merge
   BOUND  rename

   Each surface with its state, and required marking the ones the bounded set depends on. BOUND is a surface that works within stated bounds and fails closed outside them. The line saying a fully general Git replacement is not ready is the headline worth carrying into any plan: this is a coexistence path today.

When the answer looks wrong

An empty or partial answer can reflect coverage, repository state, or an error. Each row below says what the state means and what to do next.

• Git export destination ... is inside the Kin working repository

  Export writes a new repository, so it refuses a path underneath the one it is reading from.

  Give --output a sibling path. The message also names the other command, the one that installs exact Git in place and steps Kin out of the way; read what it prints before you run it.

• error: unexpected argument '<path>' found

  The destination is a flag, not a positional argument.

  Use kin git export --output <path>.

• git status stays dirty after kin commit.

  The change is recorded in Kin authority. Git has not been asked to do anything, so it still sees a modified file.

  Leave it while you evaluate, commit with Git as well if you want both moving together, or export when you want the Git repository to carry the change.

• no live graph was reachable, so the entity and relation counts above are the admitted overlay's

  kin diff answered from durable authority because no daemon was running for this repository. It says so rather than reporting zero changes.

  Start the repository daemon by running any query, then ask again.

• Error: no graph snapshot found at .../.kin/kindb/graph.kndb

  kin backup create works on a graph snapshot, and this store has not written one yet.

  Treat the Git repository you admitted from as the backup during an evaluation, and keep the disposable copy this page asked for.