RepoKit

Transform chaotic code folders into professional, organized repositories that work seamlessly with GitHub and teams.

RepoKit automates the creation of standardized Git repositories with professional structure, worktree-based and branching workflows, and GitHub/Gitlab/etc deployment pipelines. Whether you're starting fresh or organizing existing code, RepoKit provides the structure and tools for professional development.

Why RepoKit?

Before: Scattered files, no organization, deployment nightmares
After: Professional structure, team-ready, GitHub-ready, portfolio-worthy

New to RepoKit? Read Why RepoKit Exists for the complete picture.

Features

Core Capabilities

Universal Bootstrap System: Analyze and migrate ANY project to RepoKit structure
Standardized Repository Structure: Consistent directory layout with standard folders
Branch Strategies: a single main branch with private notes kept out of git, or the multi-branch model (main, dev, staging, test, live, and a local-only private branch)
Worktree Management: Git worktrees for efficient branch isolation and parallel development
Private Content Protection: Secure local-only content that never gets pushed
GitHub/GitLab Integration: Automated repository creation and deployment
AI Development Integration: Built-in Claude AI assistance with workflow documentation
Two template systems: the structure every project gets, then the code type on top -- a language layer and, below it, layers named by the choice they answer (how it is built, what it uses, what it is), composed with --with or taken whole as a preset (--language python,c-cpp, --with c-cpp/cmake-app, --with cmake-lib,qt); repokit list shows them; a new language is a folder and a manifest entry, not code
Comprehensive Test Framework: Unit, integration, and end-to-end testing

Universal Project Support

Empty Projects: Start fresh with optimal structure
Existing Code: Preserve your files while adding RepoKit benefits
Git Repositories: Maintain full history while upgrading workflow
Complex Projects: Handle multi-branch, multi-contributor scenarios
Legacy Codebases: Safe migration with conflict resolution

📦 Installation

# Install from source
git clone https://github.com/djdarcy/git-repokit.git
cd git-repokit

# Install in development mode with all dependencies
pip install -e ".[dev]"

# Or install for regular use
pip install -e .

🎯 Quick Start

Create a New Project

# Basic project creation
repokit create my-awesome-project --language python

# A C/C++ project: the language's layer plus its default archetype (cmake-app)
repokit create my-tool --language c-cpp

# A preset names its language; several languages stack in the order given
repokit create my-tool --with c-cpp/msbuild
repokit create my-tool --language python,c-cpp

# Compose layers below the language (bare names when unique; the tool orders them)
repokit create my-tool --with setuppy
repokit list            # every language's presets and layers, one screen

# Create and deploy to GitHub in one command
repokit create my-project --language python --publish-to github --private-repo

# Create with AI integration
repokit create my-project --ai claude --publish-to github

Languages and archetypes (the code-type layers)

Every project gets the same structure (README, CONTRIBUTING, .github/, .gitignore, the vault, repokit-common). --language adds the code type on top, from repokit/templates/layers/: each language has a layer and a default archetype, and an archetype (--with LANG/NAME) adds its own layer and implies its language. With several languages and no --with, the first language is the primary one and only its default archetype applies (two archetypes would both claim the settings and build files); the other languages add their language layers. A later layer's file replaces an earlier one; a file named <name>.rkappend is appended instead (so each language adds its lines to .gitignore); __RK_NAME__ tokens in file names and contents become the project's names (my-tool, my_tool, MY_TOOL, MyTool, the author, the year, a GUID). Workflow files are copied unchanged. Files are written byte for byte, so a header's BOM or a .sln's line endings are what the layer holds. repokit list prints the known languages, presets and layers; an unknown name, or one whose layer is not built yet, stops before anything is created and names what is known. generic (the default) adds no code-type files.

--with takes a list. A token is a preset (python/pypi, the tested lists in the table below), a layer qualified by its language (c-cpp/qt), or a bare name when only one language has it (setuppy; qt is refused naming both). Every layer belongs to a facet, the question it answers -- where it runs, which dialect, how it is built or packaged, what it uses, what it is -- and the tool orders a list by facet, fills in what a layer implies (its language at least), and refuses two answers to a one-answer question (pypi,setuppy). A list that equals a preset is recorded as that preset in .repokit.json; any other list is assembled by the rules and noted once as not a tested preset. .repokit.json records layers, every layer in the order applied.

CI comes from the layers too: ci-python.yml with the Python layer (a matrix of pytest runs and a build), ci-c-cpp.yml with the cmake-app archetype (CMake, CTest on three operating systems); the README's workflow badge names the file that exists, and a project with no CI has no workflow badge. The structure writes .gitattributes (line-ending normalisation, and scripts/repokit-common/** linguist-vendored so GitHub does not count the vendored tooling as the project's language) and a CHANGELOG.md with the first version's heading and links, which git-repokit-common's version tool expects.

Language	Default archetype	Archetypes
`python`	`python/pypi` (`pyproject.toml` with a dynamic version, the package with `cli.py` and `_version.py`, tests, the publish-on-release workflow -- the shape of git-repokit-template's projects)	`python/setuppy` (`setup.py` + `requirements.txt`, the output before 0.7.1); `python/script` (one module reading `VERSION`, its own small CI, no packaging -- the simple-projects floor); `python/comfyui`, `python/django`, `python/qt` announced
`c-cpp`	`c-cpp/cmake-app` (CMake presets, a vcpkg manifest, CTest, a build-time version stamp, CI)	`c-cpp/msbuild` (a Visual Studio solution), `c-cpp/minimal` (one source file, `Makefile` + `build.bat`); `c-cpp/cmake-lib` and `c-cpp/qt` announced. All three build as generated with Visual Studio 2022's tools (`tests/test_layers_c_cpp.py`); the version lives in `include/<name>/version.h`, which CMake, the `.rc` resource and the code all read
`js-ts`	`js-ts/node-package` (an npm package in TypeScript: `package.json` with an exports map, `tsconfig.json`, `src/index.ts`, `node:test` tests, publish-on-release; the layers `node`, `ts`, `node-package`)	`js-ts/script` (one `.js` run with node, reading `VERSION`, no build step -- the floor); `js-ts/claude-plugin` (a Claude Code plugin in `plugin/` with its own manifest, a SessionStart hook, `node:test` tests and the marketplace README, the marketplace manifest at the root; add `ts` for TypeScript); `js-ts/web-vite-react`, `js-ts/obsidian-plugin`, `js-ts/browser-extension`, `js-ts/comfyui-frontend` announced. The version lives in `VERSION`; the vendored version tool keeps `package.json` in step

Adopt an Existing Project

# Analyze what RepoKit will do
repokit analyze .

# Adopt in-place with safe strategy
repokit adopt . --publish-to github --private-repo

# Migrate to new structure (creates copy)
repokit migrate ./old-project ./new-project

🔧 Common Use Cases

1. Brand New Python Project

# Create project with GitHub deployment
repokit create awesome-api \
  --language python \
  --description "My awesome Python API" \
  --publish-to github \
  --private-repo \
  --ai claude

2. Existing Project Migration

# First, analyze your project
cd existing-project
repokit analyze .

# Then adopt with recommended settings
repokit adopt . \
  --migration-strategy safe \
  --publish-to github \
  --organization my-company

3. Legacy Project Modernization

# Analyze complex project
repokit analyze ./legacy-app

# Adopt with careful conflict handling
repokit adopt ./legacy-app \
  --strategy safe \
  --branch-strategy gitflow \
  --dry-run  # Preview changes first

4. Multi-Language Monorepo

# Create with custom structure
repokit create platform \
  --language generic \
  --directories "backend,frontend,shared,docs,infra" \
  --branches "main,develop,release,hotfix" \
  --publish-to github

📊 Project Analysis

RepoKit can analyze any project and provide migration recommendations:

repokit analyze /path/to/project

# Output includes:
# - Project type (empty, source_no_git, git_with_history, etc.)
# - Detected primary language
# - Migration complexity (low/medium/high)
# - Recommended migration strategy
# - Recommended branch strategy
# - Step-by-step migration plan

🌳 Branch Strategies

RepoKit supports multiple branching strategies.

Main-only (the default)

main

repokit create my-project makes the project folder the repository, on main, with:

private/ as its own git repository (ignored by the project; linked into every worktree);
git-repokit-common vendored at scripts/repokit-common/, with its hooks installed (version sync, private-content checks, test gating).

--no-common skips git-repokit-common; --private-mode branch keeps private work on a private branch only.

--license <id> writes LICENSE from the catalogue (the SPDX set GitHub and GitLab offer, plus gpl-3.0-or-later and the like, and all-rights-reserved), --license file=<path> copies a text as it is, --license none writes none; a licence is required, so with no flag the global config must name license (and license_private for --private-repo), and otherwise the create refuses and lists the catalogue. --extras funding,dependabot,stale,pr-template,release-template,roadmap,platform-support,vscode-settings,placeholders (or all) adds the optional files the old template carried; they are off unless named here or in the global config's extras list, and --no-extras turns them off. The house style, then, is a ~/.repokit/config.json such as:

{"license": "gpl-3.0", "license_private": "all-rights-reserved",
 "extras": ["funding", "dependabot", "stale", "pr-template", "release-template", "roadmap", "placeholders"],
 "github": {"username": "you", "organization": "your-org"}}

With it, repokit create NAME --language python reproduces the project tree git-repokit-template gave, which tests/test_template_parity.py keeps true; the same licence and extras land for --language c-cpp and --language js-ts.

The private-branch model

These keep your working history on a local-only private branch (repository in <name>/local/, main in <name>/github/) and move finished work to the public branches -- squashed, fast-forwarded, or selectively. A valid workflow, and RepoKit's original one, but more involved: hooks refuse private files on public branches to keep mistakes from leaking. See docs/Branch-Strategies.md.

With --with-common, these strategies also get git-repokit-common's hooks, configured to refuse private files on the public branches. repokit setup-guardrails installs the same hooks in an existing project.

Standard

private → dev → main → test → staging → live

Simple

private → dev → main

GitFlow

private → feature/* → develop → release/* → main
                  ↘                    ↗
                    hotfix/* →  →  → ↗

GitHub Flow

private → feature/* → main

Custom

repokit create my-project \
  --branches "main,develop,qa,production" \
  --worktrees "main,develop"

🔐 GitHub/GitLab Integration

With the gh CLI (simplest)

gh auth login                                   # once
repokit create my-project --github              # private repo under your account, main pushed
repokit create my-project --github --public --org MyOrg

git-repokit uses gh's login, so no token is configured here. Only public branches are pushed; a private branch never leaves your machine.

Through the REST API with a token

Initial Setup

# Store GitHub credentials (one time)
repokit store-credentials --publish-to github --token YOUR_TOKEN

# Or use environment variable
export GITHUB_TOKEN=YOUR_TOKEN

Automatic Deployment

# Create and deploy in one command
repokit create my-project --publish-to github --private-repo

# Deploy to organization
repokit create team-project \
  --publish-to github \
  --organization my-company \
  --private-repo

🤖 AI Integration

RepoKit includes Claude AI integration for enhanced development:

# Create project with AI assistance
repokit create my-project --ai claude

# This adds:
# - CLAUDE.md with project context
# - Development workflow instructions
# - Problem-solving methodology (The Process)
# - Private documentation structure

📁 Directory Structure

RepoKit creates an organized project structure:

my-project/
├── local/          # Main repository (private branch)
│   ├── docs/       # Documentation
│   ├── tests/      # Test files
│   ├── scripts/    # Utility scripts
│   ├── private/    # Local-only content
│   │   └── claude/ # AI assistance docs
│   └── ...
├── github/         # Main branch worktree
└── dev/           # Development branch worktree

🧪 Testing

RepoKit includes a comprehensive test framework:

# Run all tests
python tests/run_tests.py

# Run specific test categories
python tests/run_tests.py --unit        # Fast unit tests
python tests/run_tests.py --integration # CLI integration tests
python tests/run_tests.py --github      # GitHub API tests (live; requires token)

# Check test environment
python tests/run_tests.py --check

Every run is isolated from your git config, home directory and tokens; see tests/README.md (and python -m pytest works too). A git push runs the unit class through the vendored pre-push hook (test-command in pyproject.toml, about four seconds); the complete suite runs in CI, and before a tag run it yourself: python -m pytest -q (about seven minutes).

📚 Documentation

Getting Started

Documentation Guide - Start here for navigation
Why RepoKit Exists - Understand the problem and solution
Adoption Guide - Step-by-step tutorials for existing projects

Reference Guides

Recipes and How-Tos - Copy-paste commands for common scenarios
Branch Strategies - Branching workflows explained
Migration Guide - Universal bootstrap scenarios
Auth Guide - Authentication and credentials
Workflow Guide - Development workflows
Deployment Demo - Step-by-step deployment examples
Test Framework - Comprehensive testing documentation

💡 Pro Tip: Start with the Documentation Guide for easier perusal and recommended reading order.

🛠️ Configuration

RepoKit uses hierarchical configuration:

Default values (built-in)
Global config (~/.repokit/config.json)
Project config (./.repokit.json)
Environment variables (REPOKIT_*)
CLI arguments (highest priority)

Example Configuration

{
  "name": "my-project",
  "language": "python",
  "branches": ["main", "develop", "staging"],
  "worktrees": ["main", "develop"],
  "user": {
    "name": "Your Name",
    "email": "your.email@example.com"
  },
  "github": true,
  "private_repo": true
}

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup and guidelines. Please feel free to open issues or submit pull requests.

Like the project?

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Inspired by modern DevOps practices and GitOps workflows
Built for developers who value consistency and automation
Special thanks to the open-source community

Name		Name	Last commit message	Last commit date
.github		.github
.vscode		.vscode
configs		configs
docs		docs
repokit		repokit
scripts		scripts
tests		tests
.flake8		.flake8
.gitattributes		.gitattributes
.gitignore		.gitignore
.repokit.json		.repokit.json
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
setup.py		setup.py

Latest commit

History

Folders and files

Repository files navigation

RepoKit

Why RepoKit?

Features

Core Capabilities

Universal Project Support

📦 Installation

🎯 Quick Start

Create a New Project

Languages and archetypes (the code-type layers)

Adopt an Existing Project

🔧 Common Use Cases

1. Brand New Python Project

2. Existing Project Migration

3. Legacy Project Modernization

4. Multi-Language Monorepo

📊 Project Analysis

🌳 Branch Strategies

Main-only (the default)

The private-branch model

Standard

Simple

GitFlow

GitHub Flow

Custom

🔐 GitHub/GitLab Integration

With the gh CLI (simplest)

Through the REST API with a token

Initial Setup

Automatic Deployment

🤖 AI Integration

📁 Directory Structure

🧪 Testing

📚 Documentation

Getting Started

Reference Guides

🛠️ Configuration

Example Configuration

Contributing

License

Acknowledgments

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages