Setup Guide: Git Remote + Google Drive

A complete step-by-step guide to setting up KK with a Git hosting service (GitHub, GitLab, or Gitea) for code and commit history, plus Google Drive for large file storage. This is the recommended setup for most teams.

Table of Contents

Overview

This setup gives you the best of both worlds for your game or media project:

What you get with this setup:

How it works

Content Type Stored In Example Files
Source code Git (GitHub/GitLab/Gitea) .go, .py, .js, .cs
Config files Git (GitHub/GitLab/Gitea) .json, .yaml, .xml
Pointers to large files Git (GitHub/GitLab/Gitea) Small text references to real files
Large files (actual content) Google Drive .mp4, .fbx, .psd, .blend

What You Need

Before starting, make sure you have:

Quick check: Open a terminal and verify you have these tools: 

git --version
kk version

If both commands work, you're ready to go!

Step 1: Create Your Git Repository

First, create an empty repository on your Git hosting service. This is where your code and commit history will live.

Option A: GitHub

  1. Go to github.com/new
  2. Enter a repository name (e.g., my-game or my-project)
  3. Important: Leave all initialization options unchecked:

❌ Do NOT check these boxes:

✅ KK will handle all of this for you!

  1. Set visibility to Public or Private
  2. Click Create repository
  3. Copy the repository URL from the next page

Your URL will look like: 

https://github.com/your-username/MyGame.git

Option B: GitLab

  1. Go to your GitLab instance and click New project
  2. Choose Create blank project
  3. Enter project name and slug
  4. Important: Do not initialize with README or .gitignore
  5. Click Create project
  6. Copy the repository URL

Your URL will look like: 

https://gitlab.com/your-username/MyGame.git

Option C: Gitea (self-hosted)

  1. Go to your Gitea instance and create a new repository
  2. Enter repository name and description
  3. Important: Initialize as empty repository
  4. Click Create
  5. Copy the repository URL

Your URL will look like: 

https://git.example.com/your-username/MyGame.git

Step 2: Initialize KK

Now create your KK project on your computer. Navigate to your project folder and run: 

# Navigate to your project directory
cd ~/Projects/my-game

# Initialize KK
kk init

On Windows: 

# Navigate to your project directory
cd C:\Users\YourName\Projects\my-game

# Initialize KK
kk init

KK will create the project structure: 

MyGame/
├── .kk/                    # KK metadata (like .git/ but KK-managed)
│   ├── git/                # KK's internal Git database
│   ├── objects/            # Local cache for large files
│   ├── config.json         # Your remotes and settings
│   ├── tracks.json         # File patterns to track
│   └── repo.json           # Project identity
└── .kkignore               # Files KK should ignore

What just happened: KK created a special Git database inside .kk/git/ instead of a regular .git/ folder. This lets KK manage large files separately while keeping all Git's power for version control.

Step 3: Add the Git Remote

Tell KK about the Git repository you created in Step 1. This is where your code and commit history will be synced.

For GitHub

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

For GitLab

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

For Gitea (self-hosted)

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

Using SSH instead of HTTPS

If you prefer SSH keys (recommended for frequent pushing), use the SSH URL: 

# GitHub SSH
kk remote add git origin git@github.com:your-username/MyGame.git

# GitLab SSH
kk remote add git origin git@gitlab.com:your-username/MyGame.git

What this command does:

You should see: 

kk: git remote 'origin' added successfully
kk: remote configured: https://github.com/your-username/MyGame.git

Verify the remote was added

kk remote list

You should see: 

default: origin
origin  type=git  provider=github  url=https://github.com/your-username/MyGame.git  push=true pull=true

Step 4: Set Up Google Drive

Now set up Google Drive to store your large files. This keeps your Git repository fast and small while giving you cloud storage for assets.

Authorize with Google

kk setup gdrive

What happens:

  1. A browser window opens (or you'll see a link to click in terminal)
  2. Sign in with your Google account
  3. Review permissions (KK requests access to Google Drive only)
  4. Click "Allow" to authorize
  5. KK creates a project folder in your Google Drive

You should see: 

kk: Opening browser for Google OAuth...
kk: Google Drive auth saved to ~/.config/KK/gdrive/default.json
kk: Drive remote 'gdrive' configured with folder-id: 1a2B3cD4eF5gH6iJ7kL8mN9oP0qR1sT2u
kk: Run 'kk push' to upload your project to Drive.
kk:     Share the project folder ID with teammates so they can clone:
kk:     kk clone drive:1a2B3cD4eF5gH6iJ7kL8mN9oP0qR1sT2u
kk: Remote ready.

💾 Save that folder ID!

The folder ID (1a2B3cD4eF5gH6iJ7kL8mN9oP0qR1sT2u) is what you'll share with teammates. You can also find it later:

  1. Open the folder in Google Drive
  2. Look at the URL: https://drive.google.com/drive/folders/<FOLDER_ID>
  3. The long string after /folders/ is your folder ID

Using multiple Google accounts

If you want to use a specific Google account or profile: 

# Use a specific account profile
kk setup gdrive --account work

# Or name the remote specifically
kk setup gdrive --name drive-work --account work

Verify Drive is configured

kk remote list

You should see both remotes: 

default: origin
origin  type=git  provider=github  url=https://github.com/your-username/MyGame.git  push=true pull=true
gdrive  type=drive provider=google-drive  push=true pull=true

Step 5: Track Large File Types (Optional)

Note: This step is optional! By default, if no custom tracking patterns are configured, KK automatically tracks all files that are not recognized as code (such as .unitypackage, .uasset, .fbx, .png, .wav, etc.) as pointers.

Explicitly running kk track is only required if you want to define custom, narrow tracking patterns (which will turn off the default "track all non-code" behavior). If you wish to specify custom patterns, use the commands below:

Common game development file types

# Video files
kk track "*.mp4" "*.mov" "*.avi" "*.mkv"

# Audio files
kk track "*.wav" "*.mp3" "*.ogg" "*.flac"

# Image and texture files
kk track "*.png" "*.jpg" "*.jpeg" "*.psd" "*.tga" "*.exr"

# 3D model files
kk track "*.fbx" "*.obj" "*.blend" "*.ma" "*.mb"

# Asset bundles
kk track "*.zip" "*.tar.gz" "*.7z" "*.rar"

All in one command: 

kk track "*.mp4" "*.wav" "*.mp3" "*.png" "*.jpg" "*.psd" "*.fbx" "*.obj" "*.blend" "*.zip" "*.tar.gz"

What gets tracked vs. what stays regular:

KK automatically knows which files should be regular based on their extension. Use kk track for the big files!

See what's being tracked

kk track list

Output example: 

Tracked patterns:
  *.mp4
  *.wav
  *.fbx
  *.blend
  *.zip

Step 6: Add, Commit, and Push

Now add your files to KK, commit them, and push to both Git and Google Drive.

Add your files

# Add all files in current directory
kk add .

# Or add specific files
kk add src/main.go Assets/character.fbx Assets/background.png

What happens:

You should see: 

code src/main.go (storing as regular file)
large Assets/character.fbx -> sha256:9f86... (12.5 MB)
large Assets/background.png -> sha256:1a2b... (2.3 MB)

Commit your changes

kk commit -m "Initial commit"

This creates a commit in KK's Git database with all your files.

Push to both Git and Drive

kk push

This one command does BOTH:

You should see: 

kk: [origin] syncing pointer history to git remote...
kk: [origin] pointer history synced
kk: [gdrive] uploading objects...
kk: [gdrive] uploaded 3 objects (14.8 MB)
kk: Push complete!

🎉 Congratulations! Your project is now set up with GitHub/GitLab/Gitea for code and Google Drive for large files!

You can verify on your Git hosting service — you'll see your source code and small pointer files. The large files are safely stored on Google Drive.

⚠️ Note on Push Performance: The first push will be slow because it must upload all large files for the first time. By default, the Google Drive remote's verify_mode is set to "local-hash". You can change this to "none" or "download" in your .kk/config.json:

To update the remote settings: 

kk remote remove gdrive
kk remote add drive gdrive --drive-folder-id <id> --drive-auth-path <path> --verify-mode none

(Alternatively, you can manually edit the "verify_mode" value under the gdrive entry in your .kk/config.json file).

Once a push completes successfully:

  1. The successfully pushed HEAD commit is saved locally in .kk/push-state.json.
  2. On your next push, kk checks if the last pushed commit is an ancestor of the current commit.
  3. If it is, kk queries Git only for the changes since that commit.
  4. It will sync and verify only the specific file(s) and object(s) you changed (e.g., just the 1 modified file/object), making subsequent pushes near-instantaneous.

Step 7: Share with Your Team

Now that your project is set up, here's how to share it with teammates.

A. Share the Git repository

Add collaborators through your Git hosting service:

B. Share the Google Drive folder

⚠️ Important: The Google Drive folder is owned by your Google account. Teammates cannot access the large files until you explicitly share the folder with them.

  1. Open Google Drive and find the KK project folder
  2. Right-click the folder → Share
  3. Add teammates' Google account emails with Editor permissions
  4. Click Send

Share the folder ID with your team so they can clone.

What to tell your teammates

Send your teammates these steps to clone and set up the project:

  1. Clone the repository: Get the source code and pointers: 
    kk clone git:https://github.com/your-username/MyGame.git --pull
  2. Authorize Google Drive with full scope: Since the shared folder is externally owned, teammates need full scope: 
    kk setup gdrive --scope full --account work
  3. Connect the shared Google Drive folder: 
    kk setup gdrive --name shared --folder 1a2B3cD4eF5gH6iJ7kL8mN9oP0qR1sT2u --account work

    Replace 1a2B3cD4eF5gH6iJ7kL8mN9oP0qR1sT2u with our actual Google Drive folder ID.

  4. Download the large assets: 
    kk pull-file .

They will need:

Teammate: Clone the Project

This section is for teammates who need to clone an existing KK project that uses GitHub/GitLab/Gitea for code and Google Drive for large files.

What you need before cloning

Before you can clone the project, make sure you have:

Quick check: Verify you have the required tools: 

git --version
kk version

If both commands work, you're ready to clone!

Step 1: Get the project information

Ask your project owner for these details:

Example Git URLs: 

# GitHub (HTTPS)
https://github.com/your-username/MyGame.git

# GitHub (SSH)
git@github.com:your-username/MyGame.git

# GitLab (HTTPS)
https://gitlab.com/your-username/MyGame.git

Step 2: Verify Git repository access

Before using KK, verify you can access the Git repository: 

# Test access (replace with your actual URL)
git ls-remote https://github.com/your-username/MyGame.git

If you see a list of branches: You have access! ✅

If you see "Permission denied" or "Repository not found": Ask the project owner to add you to the repository.

Step 3: Verify Google Drive access

Check if you can see the shared Google Drive folder:

  1. Open Google Drive in your browser
  2. Look for "Shared with me" on the left sidebar
  3. Find the project folder (usually named after the project)

If you can see the folder: Great! You have access. ✅

If you don't see the folder: Ask the project owner to share it with your Google account email.

Step 4: Authorize Google Drive & Connect Shared Folder

Since Google Drive needs full scope for other teammates to access folders owned by the project owner or other teammates, you must authorize KK with full scope and connect the shared folder before cloning: 

# Step 4a: Authorize with full scope
kk setup gdrive --scope full --account work

# Step 4b: Connect to the shared folder
kk setup gdrive --name shared --folder 1a2B3cD4eF5gH6iJ7kL8mN9oP0qR1sT2u --account work

Replace 1a2B3cD4eF5gH6iJ7kL8mN9oP0qR1sT2u with the actual folder ID from your project owner.

⚠️ Security Warning: --scope full grants KK access to ALL files in your Google Drive. Only use with official KK binaries from trusted sources.

Step 5: Clone the project with KK

Now clone the project using KK. Navigate to where you want the project and run:

On macOS/Linux:

# Navigate to your projects directory
cd ~/Projects

# Clone from Git and download large files
kk clone git:https://github.com/your-username/MyGame.git --pull

On Windows:

# Navigate to your projects directory
cd C:\Users\YourName\Projects

# Clone from Git and download large files
kk clone git:https://github.com/your-username/MyGame.git --pull

Using SSH instead of HTTPS:

kk clone git:git@github.com:your-username/MyGame.git --pull

What the --pull flag does:

💡 Tip: If you omit --pull, KK will clone the repository but not download large files. You can download them later with kk pull or kk pull-file .

Step 6: What happens during cloning

KK will show you progress as it clones: 

kk: cloning from git remote...
kk: repository cloned successfully
kk: downloading objects from remotes...
kk: [gdrive] scanning for missing objects...
kk: [gdrive] downloading 12 objects (45.2 MB)
kk: [=============>           ] 60% (27.1 MB / 45.2 MB)
kk: [gdrive] download complete
kk: materializing pointer files...
kk: Clone complete!

What you get after cloning:

Step 7: Enter the project and verify

# Navigate into the project
cd MyGame
 
# Check the status
kk status

# List configured remotes
kk remote list

You should see: 

On branch main
Your branch is up to date with 'origin/main'.

default: origin
origin  type=git  provider=github  url=https://github.com/your-username/MyGame.git
gdrive  type=drive provider=google-drive

Step 8: Start working!

Now you can start working on the project: 

# Make changes to files...

# Add your changes
kk add .

# Commit your changes
kk commit -m "Add new feature"

# Push to both Git and Drive
kk push

Troubleshooting Clone Issues

Issue: "Permission denied" or "Repository not found"

Cause: You don't have access to the Git repository.

Solution:

  1. Ask the project owner to add you as a collaborator
  2. Verify you're using the correct Git account
  3. For GitHub: Check your Settings → Collaborators to confirm you're listed

Issue: "Google Drive folder not found" or "Permission denied"

Cause: The Google Drive folder isn't shared with your account, or you're using the wrong Google account.

Solution:

  1. Check Google Drive → "Shared with me" for the folder
  2. Ask the project owner to share the folder with your email
  3. Make sure you're signed in with the correct Google account
  4. For externally shared folders, run these two commands: 
# Step 1: Authorize with full scope
kk setup gdrive --scope full --account work

# Step 2: Connect to the shared folder
kk setup gdrive --name shared --folder 1a2B3cD4eF5gH6iJ7kL8mN9oP0qR1sT2u --account work

Replace 1a2B3cD4eF5gH6iJ7kL8mN9oP0qR1sT2u with the actual folder ID from your project owner.

⚠️ Security Warning: --scope full grants KK access to ALL files in your Google Drive. Only use with official KK binaries from trusted sources.

Issue: Clone succeeded but large files are missing

Cause: Large files weren't downloaded during clone.

Solution:

# Navigate to project
cd MyGame

# Download all large files
kk pull-file .

This downloads and materializes all pointer files in the current directory and subdirectories.

Issue: "git remote not found" error

Cause: Git credentials aren't configured.

Solution:

# Configure Git credentials (HTTPS)
git config --global credential.helper store

# Then clone again — you'll be prompted for credentials

Issue: Clone command not found

Cause: KK isn't installed or not on your PATH.

Solution:

Daily Workflow

After initial setup, your daily workflow is simple:

Making changes

# Make changes to your files...

# Add new or changed files
kk add .

# Commit changes
kk commit -m "Add new character model"

# Push to both Git and Drive
kk push

Pulling updates from teammates

# Pull latest code and pointers from Git
kk pull

# Download any new large files
kk pull-file .

Creating branches

# Create a new branch
kk branch feature/new-enemy

# Make changes...
kk add Assets/enemy.fbx
kk commit -m "Add enemy model"

# Push branch to Git
kk push

Merging branches

# Switch back to main branch
kk checkout main

# Pull latest changes
kk pull

# Merge the feature branch
kk merge feature/new-enemy

# Push merge
kk push

Troubleshooting

Issue: "Git remote authentication failed"

Cause: Git needs your credentials.

Fix:

Issue: "Google Drive folder not found" or "Permission denied"

Cause: The Google Drive folder isn't shared with your account, or you're using the wrong Google account.

Fix:

  1. Check Google Drive → "Shared with me" for the folder
  2. Ask the project owner to share the folder with your email
  3. Make sure you're signed in with the correct Google account
  4. For externally shared folders, run these two commands:
# Step 1: Authorize with full scope
kk setup gdrive --scope full --account work

# Step 2: Connect to the shared folder
kk setup gdrive --name shared --folder 1a2B3cD4eF5gH6iJ7kL8mN9oP0qR1sT2u --account work

Replace 1a2B3cD4eF5gH6iJ7kL8mN9oP0qR1sT2u with the actual folder ID from your project owner.

⚠️ Security Warning: --scope full grants KK access to ALL files in your Google Drive. Only use with official KK binaries from trusted sources.

Issue: "Some files didn't download"

Cause: Large files may not have downloaded yet.

Fix: Run kk pull-file . after cloning.

Issue: "Repository size is too large"

Cause: Large files are being tracked as regular files.

Fix:

Further Reading