Looking for a way to manage versions and work with history of your structured data? Dolt is a version controlled relational database that combines the version control features of Git with the relational database features of MySQL. Today, we're excited announce the first version of dolt cherry-pick! This brings Dolt one more step closer to Git's feature set. With cherry-pick support, it's easy to re-apply changes from any existing commit in your database to any branch. In this post, we'll go over how to use dolt cherry-pick and explain the limitations of this first version.

What is cherry-picking?

In Git, cherry-picking applies changes that were introduced in an existing commit from any branch to your current branch. Cherry-picking is useful for updating your branch with specific changes like a bug-fix from a branch that it is either hard to merge or has unnecessary changes that you do not want. This is the main difference between cherry-pick and merge. With that said, merge is generally preferable as cherry-pick can cause issues in future merges creating duplicate changes with different commit hashes.

The difference between the cherry-pick commit and its parent commit is what we call "changes introduced", and it is applied on "current HEAD", the working set of the currently checked out branch. A cherry-pick commit creates a new commit by default. This requires the working set to be clean to avoid any merge conflicts. When we cherry-pick a commit, we create the exact duplicate change in two different branches, so be sure to keep track of which commit was cherry-picked from which branch to avoid conflicts in future merges and cherry-picks.

dolt cherry-pick

The main functionality of cherry-picking, applying changes from a commit to your working set, is supported in dolt cherry-pick. In order to keep it simple and get a first version out quickly for customers, we focused on the main functionality excluding additional options for this version. Here is a list of notes and limitations of this version:

1. Only a single commit is allowed to be cherry-picked at a time, but it does not restrict running dolt cherry-pick multiple times with each commit the user needs.

2. dolt cherry-pick is available for the CLI only. Dolt supports version control operations via the CLI and SQL. In SQL, write operations are exposed as stored procedures and read operations are exposed as system tables. Stay tuned for the dolt_cherrypick() stored procedure.

3. Cherry-picking a commit that causes conflicts is not allowed. An attempt to cherry-pick causing conflicts will result in failure and leave the working set clean.

4. We only support data changes in this initial version – cherry-picking commits with schema changes is not supported yet. To work around this, you can commit schema changes on your current branch to match the schema in the cherry-pick commit, and then run cherry-pick.

5. Any flag options that Git supports are not supported in this version, so we follow the default options of git cherry-pick. We do not allow fast-forwarding, dolt cherry-pick command always creates a new commit using the same commit message of cherry-pick commit. Cherry-picking a merge commit is not supported as we do not have the option to specify which parent to use as the mainline.

Cherry-picking in action 🍒

This may seem like a lot of restrictions, but, this is only the first version of dolt cherry-pick, focusing on the most common case of direct row changes with INSERT, UPDATE and DELETE queries. With this initial support, cherry-picking can still be quite useful.

This is a simple demo of how dolt cherry-pick works. Here is in main branch.

$ dolt sql -q "SELECT * FROM products"
+----+------------+
| id | name       |
+----+------------+
| 1  | Dolt       |
| 2  | DoltHub    |
| 3  | DoltLab    |
| 4  | HostedDolt |
+----+------------+
$ dolt log --oneline
i45j5ae8b0cqh1h51en53r3u2ofg3bgb (HEAD -> main) add HostedDolt
d8hetm38tu9v07jk8u2lls8urefihsi7 add DoltLab
7bfiqv91v7tulchau3mrpd4ukbhh1t6k add DoltHub
14ovq1mlt2mqv29p11h68r884j87t20l add DoltHub
7gqh38bi0rnitmp548hqm2kbj6akj1k7 create products table
ttbk2vvh78hi2lcgkjf1u7s0skdsfick Initialize data repository

Let's cherry-pick commit 7bfiqv91v7tulchau3mrpd4ukbhh1t6k which inserts row (2, 'DoltHub'). You can either use

$ dolt cherry-pick 7bfiqv91v7tulchau3mrpd4ukbhh1t6k

or

$ dolt cherry-pick main~2

Here, we are in other branch.

$ dolt sql -q "SELECT * FROM products"
+----+------+
| id | name |
+----+------+
+----+------+
$ dolt log --oneline
7gqh38bi0rnitmp548hqm2kbj6akj1k7 (HEAD -> other) create products table
ttbk2vvh78hi2lcgkjf1u7s0skdsfick Initialize data repository
$ dolt cherry-pick 7bfiqv91v7tulchau3mrpd4ukbhh1t6k
commit v2s0mh49gqkmebsfdh8p7p5b7kg1j5n0 (HEAD -> other) 
Author: jennifersp <jspurevsuren@gmail.com>
Date:  Wed Jun 29 12:02:58 -0700 2022

        add DoltHub
          
$ dolt sql -q "SELECT * FROM products"
+----+---------+
| id | name    |
+----+---------+
| 2  | DoltHub |
+----+---------+

You can see that we only applied the change that was introduced in commit 7bfiqv91v7tulchau3mrpd4ukbhh1t6k to the current HEAD of other branch.

Need more support for cherry-pick?

Let us know if you need specific support for cherry-pick. The easiest way is to join on Discord, or you can file an issue on GitHub. It can be something Git supports, or not. The documentation page for dolt cherry-pick will have the most recently updated details about what options are supported for cherry-pick at the moment.