mrchef 0.14.1

Metarepo Chef

Mr. Chef

👨‍🍳 Meta-Repo Chef. Culinary git helper to work with code buffets.

Why

It has features that no other meta-repo manager has:

• Code is 100% reproducible.
• Full freeze-warmup-freeze coding cycle.
• Upstream patching supported.
• Downstream patching supported.
• Mixed and multi-patching repo supported.
• Automated updates.
• Automatic disk space economization with git-autoshare.
• Food! 🥘

Let's dive in. Imagine you need to create an app that requires many unrelated modules to be properly glued together. How would you organize your source code?

There are multiple answers to that question:

• Use separate repos and glue them together through packaging. But what if some code you need isn't properly packaged? What if some dependencies need more than 1 patch to work?
• Use a monorepo. However, what happens if some parts are open source and you need to upstream or review changes?
• Use git submodules. However, that requires that every time you do a git checkout... or almost any git command..., you need to use some --recurse-submodules flag. Also it gives a lot of headaches when you move files around and perform basically any operation. And what if you need to merge 2 upstream patches?
• Use git subtrees. But then, you need even more deep knowledge than with submodules to be able to review or publish patches. And again, how to merge more than one patch?
• Use Pijul. But the world isn't ready for it yet. Still we need Git.

The solution is to use a meta-repo. There are many meta-repo managers out there, but none of them has all the features that I already told you about Mr. Chef.

Glossary

Mr. Chef introduces a new code management concept based on the metaphor of a buffet. Use this glossary to understand the rest of the recipe... readme! Sorry...

• Buffet is the main git repository that contains all the instructions to build it.
• The config file is a file named mrchef.toml that stands in the root of your buffet and configures what Mr. Chef should do.
• The kitchen is the root folder, inside the buffet, where you can find the meals. It's configured inside the config file.
• A meal is like a git submodule: another git repo inside your kitchen.
• A spice is a patch that is added to a meal.
• The freezer is where we store the gory details needed to make the kitchen 100% reproducible. Mr. Chef saves it in a file called .mrchef.freezer.toml.
• Warming up means getting meals outside of the freezer and putting them in the kitchen, ready to cook!
• Freezing means writing a new freezer that can reproduce what's currently warmed up in the kitchen.

How

Using CLI

Install it:

pipx install mrchef

Usually you start by creating a new configuration file:

mrchef init

It will create a new mrchef.toml file with some comments about how to use it. You can delete them once you know how to do it.

Now, you will need to add a meal:

mrchef meal-add kitchen/hello https://github.com/octocat/Hello-World master

💡 Mr. Chef uses git-autoshare automatically. It will help you if you need to clone huge repos! But you have to install it and configure it before adding the meals.

You can add more meals just like that.

Maybe you need to apply a couple of spices to the meal? OK:

mrchef spice-add kitchen/hello https://github.com/octocat/Hello-World/pull/2256
mrchef spice-add kitchen/hello https://github.com/octocat/Hello-World/pull/34

Did master get new commits? Or did those PRs get updated? Update everything:

mrchef update

Cool, huh? 😏 Mr. Chef can do more things! To see all commands and what they do:

mrchef --help-all

Using Python

Install it:

pip install mrchef

Use it:

import mrchef

Using Nix

Install it:

nix profile install gitlab:moduon/mrchef

Did I say buffets are 100% reproducible? Nothing better than Nix for that job.

Go read the flake. You'll find helpers ready to convert a buffet into aggregated source code. Read the minimal test to understand how to use them. Ready to replace git submodules?

Keep in mind this if using nix:

• You must enable parse-toml-timestamps experimental feature.

• Most mrchef-based derivations will benefit a lot from pre-filtering the sources before the build. Typically, by just including ./mrchef.toml, ./.mrchef.freezer.toml and ./kitchen/ (if it exists and the kitchen is named like that), you will have all you need to build.

• Make sure you add require_nar_hash = true to your mrchef.toml, so Mr. Chef will add those hashes when freezing. This way, Nix evaluation won't have to be serialized.

Dealing with private repos

Mr. Chef runs in your environment.

If you're cloning a private Git repository, probably it'll be better if you clone it with SSH. This way, your SSH agent will deal with authentication and Mr. Chef will have nothing special to do.

If you're adding a spice from a Github PR found in a private repository, install Github CLI and log in with gh auth login. Mr. Chef will use it to authenticate. Otherwise you can export an environment variable named GITHUB_TOKEN.

Who

Created and maintained by Moduon Team.

Original idea by Jairo Llopis.

Where

Anywhere you want! 🎁 It's GPL 3.0+.