Merges

Merging branches

To merge a branch into your current branch, use the DOLT_MERGE() stored procedure:
1
CALL DOLT_MERGE('feature-branch');
Copied!
This function returns whether the merge was a fast-forward or not and whether or not there are conflicts generated by the merge.
1
+--------------+-----------+
2
| fast_forward | conflicts |
3
+--------------+-----------+
4
| 1 | 0 |
5
+--------------+-----------+
Copied!
Note, if you are running DOLT_MERGE() with AUTOCOMMIT on (the default of most clients), the merge will fail in the presence of conflicts. You must merge and clear conflicts in the same SQL transaction with default Dolt settings. To do this, you must disable AUTOCOMMIT and call COMMIT manually to complete a transaction. Later in this document we will tell you how to change this setting for advanced use cases.
If your merge is not a fast-forward you are required to create a Dolt commit to persist the merge. For example, you can run CALL DOLT_COMMIT('Merged feature-branch').

Conflicts

Merging branches can create conflicts, which you must resolve before you can commit your transaction. If a merge creates conflicts, the DOLT_MERGE() function will return a non-zero result in the conflicts column.
Merges can generate conflicts on schema or data.

Schema

Merges with schema conflicts cannot be resolved using SQL. The merge will fail. For instance a merge that adds the same column name with two different types will fail.
1
CALL DOLT_MERGE('schema-change');
2
Error 1105: schema conflicts for table test:
3
two columns with the name 'c2'
Copied!

Data

Merges with data conflicts can be resolved using SQL. Conflicts must be resolved in the same SQL transaction by default. You can find which tables are in conflict by querying the dolt_conflicts system table:
1
SELECT * FROM dolt_conflicts;
2
+--------+---------------+
3
| table | num_conflicts |
4
+--------+---------------+
5
| people | 3 |
6
+--------+---------------+
Copied!
Each database table has an associated dolt_conflicts table, which you can SELECT, UPDATE and DELETE rows from to examine and resolve conflicts. For the hypothetical people table above, the conflict table looks like this:
1
DESCRIBE dolt_conflicts_people;
2
+------------------+-------------+------+------+---------+-------+
3
| Field | Type | Null | Key | Default | Extra |
4
+------------------+-------------+------+------+---------+-------+``
5
| base_occupation | varchar(32) | YES | | | |
6
| base_last_name | varchar(64) | YES | | | |
7
| base_id | int | YES | | | |
8
| base_first_name | varchar(32) | YES | | | |
9
| base_age | int | YES | | | |
10
| our_occupation | varchar(32) | YES | | | |
11
| our_last_name | varchar(64) | YES | | | |
12
| our_id | int | YES | | | |
13
| our_first_name | varchar(32) | YES | | | |
14
| our_age | int | YES | | | |
15
| their_occupation | varchar(32) | YES | | | |
16
| their_last_name | varchar(64) | YES | | | |
17
| their_id | int | YES | | | |
18
| their_first_name | varchar(32) | YES | | | |
19
| their_age | int | YES | | | |
20
+------------------+-------------+------+------+---------+-------+
21
22
SELECT * FROM dolt_conflicts_people;
23
+-----------------+----------------+---------+-----------------+----------+----------------+---------------+--------+----------------+---------+------------------+-----------------+----------+------------------+-----------+
24
| base_occupation | base_last_name | base_id | base_first_name | base_age | our_occupation | our_last_name | our_id | our_first_name | our_age | their_occupation | their_last_name | their_id | their_first_name | their_age |
25
+-----------------+----------------+---------+-----------------+----------+----------------+---------------+--------+----------------+---------+------------------+-----------------+----------+------------------+-----------+
26
| Homemaker | Simpson | 1 | Marge | 37 | Homemaker | Simpson | 1 | Marge | 36 | NULL | NULL | NULL | NULL | NULL |
27
| Bartender | Szslak | 2 | Moe | NULL | Bartender | Szslak | 2 | Moe | 62 | Bartender | Szslak | 2 | Moe | 60 |
28
| NULL | NULL | NULL | NULL | NULL | Student | Simpson | 3 | Bart | 10 | Student | Simpson | 3 | Lisa | 8 |
29
+-----------------+----------------+---------+-----------------+----------+----------------+---------------+--------+----------------+---------+------------------+-----------------+----------+------------------+-----------+
Copied!
For each column in the database table, the conflicts table has three columns: one for base, one for ours and one for theirs. These represent the three different values you might choose to resolve the conflict (either the common commit ancestor's values, the current table values, or the merged table values).

Resolving conflicts

To commit your transaction, you must first resolve the merge conflicts by deleting every row in every dolt_conflicts system table. This signals to Dolt that you have resolved every merge conflict to your satisfaction. There are several different strategies you could use, which you must repeat for every table in conflict.

Take ours

To use the values in the current working set (rather than the merged values), simply delete from the dolt_conflicts table without changing anything else.
1
DELETE FROM dolt_conflicts_people;
Copied!

Take theirs

To use the merged values, overwriting our own, REPLACE and DELETE rows from the table using the conflicts table:
1
-- Replace existing rows with rows taken with their_* values as long
2
-- as their_id is not null (rows deleted in theirs)
3
REPLACE INTO people (id,first_name,last_name,age) (
4
SELECT their_id, their_first_name, their_last_name, their_age
5
FROM dolt_conflicts_people
6
WHERE their_id IS NOT NULL
7
);
8
9
-- Delete any rows that are deleted in theirs
10
DELETE FROM PEOPLE WHERE id IN (
11
SELECT base_id
12
FROM dolt_conflicts
13
WHERE base_id IS NOT NULL AND their_id IS NULL
14
);
15
16
-- mark conflicts resolved
17
DELETE FROM dolt_conflicts_people;
Copied!

Custom logic

It's also possible that you want your users to resolve conflicts themselves by picking which of the conflicting values to use for each row in conflict. You can build this workflow, or any other custom logic you want, with the SQL primitives above.

Committing with merge conflicts

By default, Dolt will not allow you to commit transactions that have merge conflicts, and will automatically rollback any transaction with merge conflicts when you attempt to COMMIT it. However, there may be times when you need to commit merge conflicts, for example to collaborate on resolving them with other people. To allow committing merge conflicts, change this system variable to 1 for every client that needs to commit merge conflicts:
1
set @@dolt_allow_commit_conflicts = 1;
Copied!
The server will not allow you to create new Dolt commits (with the dolt_commit() system function or with the @@dolt_transaction_commit system variable) if the working set has conflicts. You must resolve conflicts before creating a Dolt commit.