How KK Works

KK is a wrapper around Git. It does not replace Git history. It controls how large files enter the repository.

Scope: KK is a client-side file management and large-object storage tool. It does not require GitHub, GitLab, or any other git hosting service. There is no server and no pull requests. Git history stays local by default. Optionally, you can push pointer history to a GitHub / GitLab remote with kk remote add git — binary objects are always stored separately on your KK storage driver.

Daily workflow

┌──────────────────────────────────────────────────────────────────┐
│  Machine A (author)                                              │
│                                                                  │
│  kk add .          → stage files, convert large ones to pointers│
│  kk commit -m "…"  → record snapshot in local git history       │
│  kk push           → upload file mirror + large objects          │
│                           │                                      │
└───────────────────────────┼──────────────────────────────────────┘
                            │  driver (Google Drive / NAS / rclone)
┌───────────────────────────┼──────────────────────────────────────┐
│  Machine B (teammate)     │                                      │
│                           ▼                                      │
│  kk clone <spec>   → download mirror, create local git commit   │
│  kk pull-file .    → materialise all large files on demand      │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

Push (Machine A)

kk add .
kk commit -m "update assets"
kk push                    # syncs file mirror + uploads large objects

kk push does three things:

Mirrors the committed project files to <driver>/<ProjectName>/
Uploads any new SHA-256 objects for large files
Pushes pointer history to any push-enabled type=git KK remote

Pull (Machine B)

First time on a new machine:

kk clone drive:<project-folder-id> --pull
# or
kk clone local:/Volumes/NAS/KK/MyGame --pull

After the project is already cloned — get latest large files:

kk pull-file .          # download and materialise all pointer files

⚠️ Important: kk pull is not the command for syncing large files. kk pull wraps git pull and only syncs git commit history from a git remote. In a KK-only workflow with no git remote configured, kk pull instead downloads and merges history bundles from the object storage remote automatically. Use kk pull-file . to download large files at any time.

Hidden Git database

KK stores the Git database in .kk/git and calls Git with:

git --git-dir=.kk/git --work-tree=. <command>

That lets KK keep the project root free of a .git/ folder while still using Git's proven history model.

Pointer files

Tracked large files are replaced by text pointers before staging:

version kk-lfs-1.0.0
oid sha256:<hash>
size <bytes>

The real bytes are stored in .kk/objects under a content-addressed path.

Default Tracking Behavior

By default, if no custom tracking patterns are configured in .kk/tracks.json, KK automatically tracks all files that are not recognized as code (e.g., .unitypackage, .uasset, .fbx, .png, .wav, etc.). Code files (such as .go, .cs, .cpp, .h, .html, etc.) always stay as regular files in Git.

If you define custom tracking patterns using kk track <pattern>, KK will switch to only tracking files that match your custom patterns, while still keeping code files exempt.

Download on demand

A checked-out project can contain only pointer files. kk pull-file path downloads and verifies the real object only when needed.

Materialise a single file

kk pull-file Assets/cinematic.mp4

Materialise everything at once

kk pull-file .          # materialize all pointer files
kk pull-file --all      # identical to .

Materialise a directory subtree

kk pull-file Assets/         # only pointer files under Assets/

Adding a Google Drive remote

KK supports two Google Drive drivers. Pick one — you don't need both.

Native Google Drive (`drive` — recommended)

kk setup gdrive

This authenticates with Google, creates the KK/<ProjectName>/ folder on Drive, and registers the remote.

Google Drive via rclone (`rclone`)

Requires rclone installed and a Drive remote configured.

# Minimal:
kk remote add rclone gdrive --remote gdrive:KK/MyGame --push true --pull true

Adding a Git remote (GitHub / GitLab / Gitea)

Add a git remote

kk remote add git github https://github.com/your-username/MyGame.git

KK will then automatically push the lightweight pointer history to that remote on every kk push.

⚠️ No server-side deletion tracking

Warning: KK does not host or control your storage driver. All files — project mirrors, large-file objects, and manifests — live directly on your chosen storage driver. KK itself runs no server.

This means:

Anyone with write access to your driver folder can delete, overwrite, or corrupt objects
KK will not be notified of external deletions
Recommendations: Restrict folder access, keep a local copy, audit periodically with kk fsck

Commit history without GitHub / GitLab

KK can store and sync the full Git commit history through your existing object-storage remote — with no GitHub / GitLab account required.

How it works — incremental bundles

KK uses native git bundles to pack and transport history:

<remote-root>/
  history/
    refs.json            ← branch tips + bundle list metadata
    main/
      full.bundle          ← complete history up to the first push
      inc-000001.bundle    ← incremental: commits since full.bundle
      inc-000002.bundle    ← incremental: commits since inc-000001

Fetch history (no merge)

kk fetch

Pull history (fetch + merge)

kk pull                # fetch history bundles then merge current branch
kk pull --no-merge     # fetch bundles only — review before merging

Clone with full history

kk clone local:/Volumes/NAS/KK/MyGame --history
kk clone drive:<folder-id> --history --pull

Deduplication and retention

Large objects are content-addressed by SHA-256. If two branches point to the same file bytes, they share the same object. Objects are retained while any reachable Git commit still contains a pointer to them.