bgit - Version Control for AI Models

Git-native interface for Bread SDK that makes AI model baking feel like regular software development.

Documentation: For comprehensive guides, configuration reference, and advanced workflows, see the Bread Documentation.

What is bgit?

bgit is a git-based interface that allows you to access Bread's model weight update system.

• input.yml = your changes to your model: Interact with this file to make changes to the current version of the model's weights
• Commits = Versions: Each commit is a step in 'weight space' - changes you make that lead to new model behaviors
• Branches = Experiments: Run bakes off different model versions. A branch let's you make changes to a model. Once you like one, you can "merge" that model into main
• README = History: Auto-generated documentation
• Run = Bake: Run operations manually with bgit run - this process begins the training process on the GPUs
• recipe.yml: Auto-generated file that documents your entire model history. Like a human-readable git history file
• Chat = Test: Chat with your baked models using bgit chat right after it bakes!

Think of it as version control for your AI's mind.

Philosophy

Why Git for AI Models?

AI model training has the same version control needs as software:

• Track changes over time
• Experiment safely
• Collaborate with teams
• Roll back mistakes
• Document decisions

Git already solves these problems perfectly. bgit makes git's power available for AI.

Design Principles

1. Minimal friction: Install once, use standard git commands
2. Transparency: No hidden state, everything in git history
3. Control: Run operations manually when you're ready
4. Familiarity: Git workflows developers already know
5. Independence: Each model is its own repo with its own history

--

Installation

Prerequisites

• Node.js 16+ and npm
• Git
• Bread API key (contact Bread)

Install bgit

Install globally using npm:

npm install -g @aibread/bgit

After installation, verify it's working:

bgit --version

Note: If you encounter permission errors on Linux/macOS, you may need to use sudo:

sudo npm install -g @aibread/bgit

Alternatively, you can configure npm to use a different directory for global packages to avoid needing sudo:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
npm install -g @aibread/bgit

Upgrade bgit

To upgrade to the latest version of bgit:

npm install -g @aibread/bgit@latest

Or if you used sudo for installation:

sudo npm install -g @aibread/bgit@latest

After upgrading, verify the new version:

bgit --version

Quick Start

1. Create Your First Model

bgit init <repo-name>

You'll be prompted for your Bread API key (validated automatically and saved to ~/.bgit/config.json for future use).

What gets created:

<repo-name>/
├── input.yml         # Your model configuration (YAML format)
├── README.md         # Auto-generated documentation with full instructions
├── .bread            # Internal Bread SDK mapping (auto-generated)
├── recipe.yml        # Model history and lineage (created empty, updated after each bake)
├── .gitignore        # Git ignores (Node.js + security)
└── .git/             # Git repository with hooks

2. Configure and Run

cd <repo-name>

# Edit input.yml with your configuration
vim input.yml

# Stage and commit your configuration
bgit add .
bgit commit -m "Initial model configuration"

# Run operations (stim → rollout → bake)
bgit run stim rollout bake

Note: For detailed instructions, workflow examples, and command reference, see the README.md file generated in your repository after running bgit init. Learn how to bake here

How It Works

The Git Workflow

Edit input.yml → Stage → Commit → Run Operations → Check Status

Every change to your input.yml file represents a new model version. Your commit messages document what changed. After successful bakes, input.yml sections (PROMPT, TARGET, BAKE) are automatically commented out (preserved as comments) for your next iteration.

Available Commands

Core Commands

• bgit init <repo-name> - Initialize a new Bread model repository
• bgit add [files...] - Stage files for commit (wraps git add)
• bgit commit [options] - Commit changes (wraps git commit)
• bgit run <operations...> - Run operations: stim, rollout, bake (use --detach for long-running bakes)
• bgit status - Show status of stim, rollout, and bake operations
• bgit fetch - Fetch results from detached bake operations

Output Commands

• bgit stim [--limit <n>] [--count] - View stim outputs or count
• bgit rollout [--limit <n>] [--count] - View rollout outputs or count

Model Management

• bgit models - List all available models
• bgit target ls - List all targets
• bgit target <name> - Get detailed target information
• bgit tree - Visualize model lineage across all branches
• bgit chat <model-name> - Chat with a baked model
• bgit metrics [bake-name] - Display training metrics chart for a bake

For detailed command usage, examples, and workflow guides, see the README.md file generated in your repository after running bgit init.

Workflow

bgit follows a standard Git workflow:

1. Edit input.yml with your configuration
2. Stage changes with bgit add .
3. Commit with bgit commit -m "description"
4. Run operations with bgit run stim rollout bake
5. Check status with bgit status

After successful bakes, input.yml sections are automatically commented out (preserved as comments) for your next iteration. Use branches for experiments and merge successful ones back to main.

For detailed workflow examples, branching strategies, and best practices, see the README.md file generated in your repository after running bgit init.

Advanced Usage

Multiple Models

Each model should be its own independent git repository. Each has its own git history, branches, and configuration.

API Key Management

The API key is stored in ~/.bgit/config.json or can be set via environment variable:

export BREAD_API_KEY=your-api-key-here

For advanced topics including team collaboration, branching strategies, merge behavior, and repository structure, see the README.md file generated in your repository after running bgit init.

Configuration

The input.yml file contains three main sections:

• PROMPT: Teacher and student prompts
• TARGET: Training data generation configuration
• BAKE: Model training settings

The generated input.yml includes documentation links and comments to guide you. For detailed configuration examples and explanations, see the README.md file generated in your repository after running bgit init.

Troubleshooting

bgit: command not found

The package isn't installed globally. Install it using:

npm install -g @aibread/bgit

If you're developing locally from this repository:

npm install
npm run build
npm link  # Creates a symlink for local development

Or use npx to run without installing:

npx @aibread/bgit <command>

Invalid API key

Check your API key:

# Check environment variable
echo $BREAD_API_KEY

# Check config file
cat ~/.bgit/config.json

Or re-run bgit init and enter a valid key when prompted.

.bread file not found

The .bread file is auto-generated by the pre-commit hook. If it's missing:

# Manually update it
bgit update-bread $(pwd)

Operations fail

Check the error output. Common issues:

• Invalid prompt names in YAML
• Incorrect repo name
• API rate limits
• Network connectivity issues

Check status with bgit status to see what failed.

Chat not working

Make sure:

• The model name is correct (check with bgit status after a successful bake)
• The API key is valid
• You have network connectivity to the Bread API

File Structure Reference

In this repo (bgit package)

bread_sdk_git_interface/
├── package.json              # Node.js package definition
├── tsconfig.json            # TypeScript configuration
├── source/                  # Source code
│   ├── cli.tsx              # Main CLI entry point
│   ├── cli/
│   │   └── commands/        # Command implementations
│   │       ├── init.tsx     # Initialize repository
│   │       ├── git.ts       # Git wrappers (add, commit)
│   │       ├── run.tsx      # Run operations
│   │       ├── status.tsx   # Check status
│   │       ├── outputs.tsx  # View outputs
│   │       └── chat.tsx     # Chat with models
│   ├── config/              # Configuration management
│   ├── sdk/                 # Bread SDK client wrapper
│   ├── git/                 # Git utilities
│   └── templates/           # Template files
│       ├── input.yml.template
│       ├── README.md.template
│       ├── .gitignore.template
│       ├── .bread.template
│       ├── pre-commit.template
│       ├── post-merge.template
│       └── .gitattributes.template
└── dist/                     # Compiled JavaScript (after build)

In each model repo (after bgit init)

<repo-name>/
├── input.yml         # Your model config (edit this)
├── README.md         # Auto-generated documentation with full instructions
├── recipe.yml        # Model history and lineage (created empty, updated after each bake)
├── .bread            # Internal mapping (auto-generated)
├── .gitignore        # Git ignores
└── .git/             # Git repository
    └── hooks/
        ├── pre-commit  # Auto-updates .bread file
        └── post-merge  # Handles merge conflicts

Development

Building

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

Testing

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

Contributing

This is an early version. Feedback and contributions welcome!

Found a bug? Open an issue. Have an idea? Open a pull request. Need help? Check the Bread SDK documentation.

Related Projects

• Bread SDK - The underlying SDK
• Bread Documentation - Official docs

License

MIT

Support

• Email: [email protected]
• GitHub Issues: Create an issue
• Documentation: Bread SDK Repo