Mergiraf

https://mergiraf.org/
Admin
Mergiraf is a syntax-aware Git merge conflict resolver that uses language understanding to...
Tokens:17,721
Snippets:232
Trust Score:8.2
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Mergiraf from source or crates.io

Source: https://mergiraf.org/installation.html

Use Cargo to build from a local clone or install directly from the crates.io registry.

```bash
cargo install --path .
```

```bash
cargo install --locked mergiraf
```

--------------------------------

### Clone and test Mergiraf with example repository

Source: https://mergiraf.org/usage.html

Demonstrates basic usage of Mergiraf by cloning an example repository and performing a merge.

```bash
$ git clone https://codeberg.org/mergiraf/example-repo
$ cd example-repo
$ git merge origin/other-branch
```

--------------------------------

### Install Mergiraf via cargo-binstall

Source: https://mergiraf.org/installation.html

Use the cargo-binstall utility to fetch pre-compiled binaries from Codeberg.

```bash
cargo binstall mergiraf
```

--------------------------------

### Define Node Signatures

Source: https://mergiraf.org/adding-a-language/enabling-commutative-merging.html

Example configuration for defining signatures for using directives, field declarations, and method declarations.

```rust
__
signature("using_directive", vec![vec![]]),
signature("field_declaration", vec![vec![Field("name")]]),
signature("method_declaration", vec![
    vec![Field("name")],
    vec![Field("parameters"), ChildType("parameter"), Field("type")]
]),
```

--------------------------------

### Conflict Resolution Examples

Source: https://mergiraf.org/print.html

Code snippets representing different states of a file during a merge conflict.

```csharp
using System;
using System.Collections.Generic;
```

```csharp
using System;
```

```csharp
using System;
using System.IO;
```

--------------------------------

### JSON Merge Conflict Example

Source: https://mergiraf.org/print.html

Demonstrates the input files and the resulting conflict output when merging JSON objects with conflicting key additions.

```json
__
{
    "new_letter": "left value",
    "alpha": "α",
    "beta": "β",
    "gamma": "γ",
    "delta": "δ"
}
```

```json
__
{
    "alpha": "α",
    "beta": "β",
    "gamma": "γ",
    "delta": "δ"
}
```

```json
__
{
    "alpha": "α",
    "beta": "β",
    "gamma": "γ",
    "delta": "δ",
    "new_letter": "right value"
}
```

```json
__
{
    "new_letter": "left value",
    "alpha": "α",
    "beta": "β",
    "gamma": "γ",
    "delta": "δ",
    "new_letter": "right value"
}
```

```json
__
{
<<<<<<< LEFT
    "new_letter": "left value",
||||||| BASE
=======
    "new_letter": "right value",
>>>>>>> RIGHT
    "alpha": "α",
    "beta": "β",
    "gamma": "γ",
    "delta": "δ"
}
```

--------------------------------

### Deletion Conflict Example Revisions

Source: https://mergiraf.org/print.html

Example code snippets showing how different revisions modify or delete elements, illustrating a known issue in 3DM merge algorithms.

```cpp
__
dismountTire(&wheel);
applyGlueAroundPuncture(&wheel.innerTube);
wait(Duration::minutes(5)); // better wait a bit longer
applyPatch(&wheel.innerTube);
```

```cpp
__
dismountTire(&wheel);
applyGlueAroundPuncture(&wheel.innerTube);
wait(Duration::minutes(2));
applyPatch(&wheel.innerTube);
```

```cpp
__
dismountTire(&wheel);
wheel.innerTube = InnerTube::new(); // otherwise I'll be late to pick up the kids
```

--------------------------------

### Define Commutative Parent with Delimiters

Source: https://mergiraf.org/print.html

Example of declaring a commutative parent that includes specific start and end delimiters.

```rust
CommutativeParent::new("object", "{", ", ", "}")
```

--------------------------------

### PCS Triples Representation

Source: https://mergiraf.org/print.html

Example of a tree converted into a set of Parent-Child-Successor triples.

```text
(⊥, ⊣, source_file)
(⊥, source_file, ⊢)
(source_file, ⊣, struct_item)
(source_file, struct_item, ⊢)
(struct_item, ⊣, "struct")
(struct_item, "struct", "MyStruct")
(struct_item, "MyStruct", field_declaration_list)
(struct_item, field_declaration_list, ⊢)
(field_declaration_list, ⊣, "{")
(field_declaration_list, "{", field_declaration)
(field_declaration_list, field_declaration, "}")
(field_declaration_list, "}", ⊢)
(field_declaration, ⊣, "first")
(field_declaration, "first", ":")
(field_declaration, ":", "usize")
(field_declaration, "usize", ⊢)
```

--------------------------------

### Define Base Revision Structure

Source: https://mergiraf.org/print.html

Example of a base revision structure used for syntax tree matching.

```text

__
struct MyStruct {
    first: usize
}
```

--------------------------------

### Tree to PCS Triples Encoding

Source: https://mergiraf.org/architecture.html

This example shows how a tree structure is converted into a set of Parent-Child-Successor (PCS) triples. Each triple `(p,c,s)` indicates that `p` is the parent of `c` and `s`, and `s` immediately follows `c` in the child list of `p`. Sentinel nodes `⊣` and `⊢`, and a virtual root `⊥` are used.

```plaintext
(⊥, ⊣, source_file)
(⊥, source_file, ⊢)
(source_file, ⊣, struct_item)
(source_file, struct_item, ⊢)
(struct_item, ⊣, "struct")
(struct_item, "struct", "MyStruct")
(struct_item, "MyStruct", field_declaration_list)
(struct_item, field_declaration_list, ⊢)
(field_declaration_list, ⊣, "{")
(field_declaration_list, "{", field_declaration)
(field_declaration_list, field_declaration, "}")
(field_declaration_list, "}", ⊢)
(field_declaration, ⊣, "first")
(field_declaration, "first", ":")
(field_declaration, ":", "usize")
(field_declaration, "usize", ⊢)
```

--------------------------------

### Mergiraf Conflict Resolution Output

Source: https://mergiraf.org/print.html

Example output showing a structured resolution of a Java file conflict compared to line-based resolution.

```text
Renamed from /home/user/.local/share/mergiraf/merges/Parser.java_o0i2JL8B/line_based.java to /home/user/.local/share/mergiraf/merges/Parser.java_o0i2JL8B/structured_resolution.java           1 1 <<<<<<< HEAD                                                                               2 . import java.lang.IllegalArgumentException;                                                 3 2 import org.codeberg.musicparser.Formats;                                                   4 . ||||||| parent of 23d19ad (Commit on my_branch)                                            5 . import java.lang.IllegalArgumentException;                                                 6 . =======                                                                                    7 . >>>>>>> 23d19ad (Commit on my_branch)                                                      8 3 import org.testng.annotations.Test;                                                        9 4                                                                                           10 5 class ParserTests {                                                                                                                                                                      /home/user/.local/share/mergiraf/merges/Parser.java_o0i2JL8B/structured_resolution.java --- 2/2 --- Text (13 Java parse errors, exceeded DFT_PARSE_ERROR_LIMIT)                               15     void parseValidInput() throws Exception  10     void parseValidInput() throws Exception .. {                                            .. {                                           16         String input = "fis g a b a b g c b  11         String input = "fis g a b a b g c b .. c a d es d c";                               .. c a d es d c";                              17                                              12                                             18 <<<<<<< HEAD                                 13         Melody melody = SUT.parse(input, For..                                              .. mats.LILYPOND);                             19         Melody melody = null;                ..                                             20         try {                                ..                                             21             melody = SUT.parse(input, Format ..                                             .. s.LILYPOND);                                 ..                                             :                                                                                              
```

--------------------------------

### TypeScript Interface Example

Source: https://mergiraf.org/adding-a-language/advanced-configuration.html

Example of a TypeScript union type interface that can cause nested structure issues during merging.

```typescript
export interface MyInterface {
  level: 'debug' | 'info' | 'warn' | 'error';
}
```

--------------------------------

### Define Left Revision Structure

Source: https://mergiraf.org/print.html

Example of a modified left revision structure compared against the base.

```text

__
struct MyStruct {
    first: usize,
    other: bool,
}
```

--------------------------------

### Git Merge Conflict Example with Mergiraf

Source: https://mergiraf.org/

This output shows a typical Git merge conflict scenario where Mergiraf has been used. It highlights the differences between the HEAD version and the incoming commit, indicating a structured resolution process.

```diff
Renamed from /home/user/.local/share/mergiraf/merges/Parser.java_o0i2JL8B/line_based.java to /home/user/.local/share/mergiraf/merges/Parser.java_o0i2JL8B/structured_resolution.java           1 1 <<<<<<< HEAD                                                                               2 . import java.lang.IllegalArgumentException;                                                 3 2 import org.codeberg.musicparser.Formats;                                                   4 . ||||||| parent of 23d19ad (Commit on my_branch)                                            5 . import java.lang.IllegalArgumentException;                                                 6 . =======                                                                                    7 . >>>>>>> 23d19ad (Commit on my_branch)                                                      8 3 import org.testng.annotations.Test;                                                        9 4                                                                                           10 5 class ParserTests {                                                                                                                                                                      /home/user/.local/share/mergiraf/merges/Parser.java_o0i2JL8B/structured_resolution.java --- 2/2 --- Text (13 Java parse errors, exceeded DFT_PARSE_ERROR_LIMIT)                               15     void parseValidInput() throws Exception  10     void parseValidInput() throws Exception .. {                                            .. {                                           16         String input = "fis g a b a b g c b  11         String input = "fis g a b a b g c b .. c a d es d c";                               .. c a d es d c";                              17                                              12                                             18 <<<<<<< HEAD                                 13         Melody melody = SUT.parse(input, For..                                              .. mats.LILYPOND);                             19         Melody melody = null;                ..                                             20         try {                                ..                                             21             melody = SUT.parse(input, Format ..                                             .. s.LILYPOND);                                 ..                                             :                                                                                              
```

--------------------------------

### Conflicting block statement additions

Source: https://mergiraf.org/print.html

Example of a conflict requiring human intervention when statement order within a block is ambiguous.

```java
__
while (true) {
    mowTheLawn();
    rechargeBatteries();
}
```

```java
__
while (true) {
    mowTheLawn();
}
```

```java
__
while (true) {
    mowTheLawn();
    returnToHomeBase();
}
```

--------------------------------

### Defining Commutative Parent in Mergiraf Language Profile

Source: https://mergiraf.org/adding-a-language/enabling-commutative-merging.html

Example of how to define a 'compilation_unit' as a commutative parent in a Mergiraf language profile, specifying newline as a separator. This allows reordering of top-level elements like using directives.

```rust
LangProfile {
    commutative_parents: vec![
        CommutativeParent::without_delimiters("compilation_unit", "\n"),
    ],
    .. 
},

```

--------------------------------

### C# Using Directives Sample

Source: https://mergiraf.org/adding-a-language/enabling-commutative-merging.html

A sample C# file demonstrating the use of 'using' directives. This code is used to illustrate how Mergiraf parses and can potentially reorder these directives.

```csharp
using System;
using System.Collections.Generic;
using System.IO;

namespace HelloWorld {

    public class SomeName {

    }
}

```

--------------------------------

### Define Test Directory Structure

Source: https://mergiraf.org/adding-a-language/testing.html

Create a directory following this naming convention to add a new test case.

```text
examples/csharp/working/add_imports
```

--------------------------------

### Sample C# File for Syntax Analysis

Source: https://mergiraf.org/print.html

A basic C# source file used to inspect how the language is parsed into a syntax tree.

```csharp
using System;
using System.Collections.Generic;
using System.IO;

namespace HelloWorld {

    public class SomeName {

    }
}
```

--------------------------------

### Build Mergiraf

Source: https://mergiraf.org/adding-a-language.html

Compile the project to generate the updated binary with support for the new language.

```bash
$ cargo build
```

--------------------------------

### Generate supported extensions list

Source: https://mergiraf.org/usage.html

Lists all file extensions supported by Mergiraf for use in .gitattributes.

```bash
$ mergiraf languages --gitattributes
```

--------------------------------

### Define pyproject.toml Test Structure

Source: https://mergiraf.org/adding-a-language/testing.html

Include a language file when testing configuration files like pyproject.toml.

```text
Base.toml
Left.toml
Right.toml
Expected.toml
language // contains "pyproject.toml"
```

--------------------------------

### Syntax Tree Output

Source: https://mergiraf.org/print.html

The resulting tree structure after parsing the sample C# file.

```text
└compilation_unit
  ├using_directive
  │ ├using
  │ ├identifier System
  │ └;
  ├using_directive
  │ ├using
  │ ├qualified_name
  │ │ ├qualifier: qualified_name
  │ │ │ ├qualifier: identifier System
  │ │ │ ├.
  │ │ │ └name: identifier Collections
  │ │ ├.
  │ │ └name: identifier Generic
  │ └;
  ├using_directive
  │ ├using
  │ ├qualified_name
  │ │ ├qualifier: identifier System
  │ │ ├.
  │ │ └name: identifier IO
  │ └;
  └namespace_declaration
    ├namespace
    ├name: identifier HelloWorld
    └body: declaration_list
      ├{
      ├class_declaration
      │ ├modifier
      │ │ └public
      │ ├class
      │ ├name: identifier SomeName
      │ └body: declaration_list
      │   ├{
      │   └}
```

--------------------------------

### Conflict Presentation Modes

Source: https://mergiraf.org/usage.html

Compare default line-aligned conflict markers with the compact syntax-aware output.

```text
<<<<<<< HEAD
<div class="vocab-panel" id="main-panel">
||||||| 15b798c
<div class="vocab-panel">
=======
<div class="vocab-panel" id="root-panel">
>>>>>>> origin/main
```

```text
<div class="vocab-panel" id=
<<<<<<< HEAD
"main-panel"
||||||| 15b798c
=======
"root-panel"
>>>>>>> origin/main
>
```

--------------------------------

### Define Makefile Test Structure

Source: https://mergiraf.org/adding-a-language/testing.html

Include a language file when testing full file names like Makefile.

```text
Base
Left
Right
Expected
language // contains "Makefile" (without the quotes)
```

--------------------------------

### Run Individual Test

Source: https://mergiraf.org/adding-a-language/testing.html

Execute the inspection helper to compare actual merge output against expected results.

```bash
$ helpers/inspect.sh examples/csharp/working/add_imports
```

--------------------------------

### Define Test File Requirements

Source: https://mergiraf.org/adding-a-language/testing.html

Each test directory must contain these four files representing the merge states.

```text
Base.cs
Left.cs
Right.cs
Expected.cs
```

--------------------------------

### Configure Language via gitattributes

Source: https://mergiraf.org/usage.html

Use gitattributes to associate specific file patterns with a language for Mergiraf.

```gitattributes
*.myjs  linguist-language=javascript
*.myjs  mergiraf.language=javascript
```

--------------------------------

### Configure Parse Error Handling

Source: https://mergiraf.org/usage.html

Enable or disable syntax-aware merging for files with syntax errors using gitattributes.

```gitattributes
# enable the option
*.c  mergiraf.allow-parse-errors

# disable the option
*.c  -mergiraf.allow-parse-errors
```

--------------------------------

### Define Language-Specific Test Structures

Source: https://mergiraf.org/print.html

Include a 'language' file when testing languages identified by full filenames like Makefile or pyproject.toml.

```text
Base
Left
Right
Expected
language // contains "Makefile" (without the quotes)
```

```text
Base.toml
Left.toml
Right.toml
Expected.toml
language // contains "pyproject.toml"
```

--------------------------------

### Tree-sitter Method Declaration Structure

Source: https://mergiraf.org/adding-a-language/enabling-commutative-merging.html

Visual representation of a method declaration node structure as parsed by tree-sitter.

```text
 └method_declaration
  ├type: predefined_type void
  ├name: identifier Run
  ├parameters: parameter_list
  │ ├(
  │ ├parameter
  │ │ ├type: predefined_type int
  │ │ └name: identifier times
  │ ├,
  │ ├parameter
  │ │ ├type: predefined_type bool
  │ │ └name: identifier fast
  │ └)
  └body: block
    ├{
    └}
```

--------------------------------

### Visualize Method Declaration AST Structure

Source: https://mergiraf.org/print.html

Displays the tree-sitter parsed structure of a method declaration to identify fields and node kinds.

```text
 └method_declaration
  ├type: predefined_type void
  ├name: identifier Run
  ├parameters: parameter_list
  │ ├(
  │ ├parameter
  │ │ ├type: predefined_type int
  │ │ └name: identifier times
  │ ├,
  │ ├parameter
  │ │ ├type: predefined_type bool
  │ │ └name: identifier fast
  │ └)
  └body: block
    ├{
    └}
```

--------------------------------

### Identify conflicting instruction additions

Source: https://mergiraf.org/conflicts.html

Illustrates a scenario where human intervention is required due to conflicting order of operations in a loop.

```java
while (true) {
    mowTheLawn();
    rechargeBatteries();
}
```

```java
while (true) {
    mowTheLawn();
}
```

```java
while (true) {
    mowTheLawn();
    returnToHomeBase();
}
```

--------------------------------

### Merge formatting and content changes in Rust

Source: https://mergiraf.org/print.html

Demonstrates merging a reformatting change on one side with a type modification on the other.

```rust
__
fn plan_route(
    start: &Location,
    end: &Location,
    settings: &RouteSettings,
) -> Route {
    todo!();
}
```

```rust
__
fn plan_route(start: &Location, end: &Location, settings: &RouteSettings) -> Route {
    todo!();
}
```

```rust
__
fn plan_route(start: &Location, end: &Location, settings: Option<&RouteSettings>) -> Route {
    todo!();
}
```

```rust
__
fn plan_route(
    start: &Location,
    end: &Location,
    settings: Option<&RouteSettings>,
) -> Route {
    todo!();
}
```

--------------------------------

### Report Merge Issues

Source: https://mergiraf.org/usage.html

Generate a reproduction archive for merge bugs using merge IDs or file paths.

```bash
$ git rebase origin/master
INFO Mergiraf: Solved 2 conflicts. Review with: mergiraf review geolocation.cpp_o0i2JL8B
Successfully rebased and updated refs/heads/my_branch.
$ mergiraf review geolocation.cpp_o0i2JL8B
$ mergiraf report geolocation.cpp_xyuSMcme
Bug report archive created:

mergiraf_report_6weNKAXO.zip

Please submit it to https://codeberg.org/mergiraf/mergiraf/issues if you are happy with its contents being published,
or reach out privately to a contributor if not.
Thank you for helping Mergiraf improve!
```

```bash
$ mergiraf report src/lib/geolocation.cpp
```

--------------------------------

### Define Language Profile

Source: https://mergiraf.org/adding-a-language.html

Register the new language by adding a LangProfile struct to src/supported_langs.rs.

```rust
LangProfile {
    name: "C#", // used for the --language CLI option, and generating the list of supported languages
    alternate_names: &[], // other possible values for --language
    extensions: &["cs"], // all file extensions for this language (note the lack of `.`!)
    file_names: &[], // the full file names which should be handled with this language
    language: tree_sitter_c_sharp::LANGUAGE.into(), // the tree-sitter parser
    // optional settings, explained below
    commutative_parents: vec![],
    signatures: vec![],
    atomic_nodes: &[],
    injections: None,
    flattened_nodes: &[],
    extra_comment_nodes: &[],
    allow_parse_errors: false,
},
```

--------------------------------

### Parsing a C# File with Mergiraf

Source: https://mergiraf.org/adding-a-language/enabling-commutative-merging.html

Command to parse a C# file using Mergiraf's command-line interface. This helps in visualizing the syntax tree and understanding how the code is structured.

```bash
$ cargo parse test_file.cs

```

--------------------------------

### Configure gitattributes for Mergiraf

Source: https://mergiraf.org/usage.html

Defines which files should be processed by the Mergiraf merge driver.

```gitattributes
* merge=mergiraf
```

```gitattributes
*.py merge=mergiraf
*.java merge=mergiraf
```

--------------------------------

### Use Mergiraf with Jujutsu

Source: https://mergiraf.org/usage.html

Commands to clone and resolve conflicts using Mergiraf within the Jujutsu version control system.

```bash
$ jj git clone https://codeberg.org/mergiraf/example-repo
$ cd example-repo
$ jj new main other-branch@origin
$ jj resolve --tool mergiraf
```

--------------------------------

### Merge Rust formatting and content changes

Source: https://mergiraf.org/conflicts.html

Shows how Mergiraf attempts to preserve formatting while applying content changes to a function signature.

```rust
fn plan_route(
    start: &Location,
    end: &Location,
    settings: &RouteSettings,
) -> Route {
    todo!();
}
```

```rust
fn plan_route(start: &Location, end: &Location, settings: &RouteSettings) -> Route {
    todo!();
}
```

```rust
fn plan_route(start: &Location, end: &Location, settings: Option<&RouteSettings>) -> Route {
    todo!();
}
```

```rust
fn plan_route(
    start: &Location,
    end: &Location,
    settings: Option<&RouteSettings>,
) -> Route {
    todo!();
}
```

--------------------------------

### Defining JSON Object as Commutative Parent

Source: https://mergiraf.org/adding-a-language/enabling-commutative-merging.html

Illustrates how to define a JSON object as a commutative parent using its node type, opening delimiter '{', closing delimiter '}', and the separator ', '.

```rust
CommutativeParent::new("object", "{", ", ", "}")

```

--------------------------------

### Merging Conflicting Using Directives

Source: https://mergiraf.org/adding-a-language/enabling-commutative-merging.html

Demonstrates a conflict scenario with three different sets of 'using' directives from left, base, and right versions. Mergiraf, with commutative parent definitions, can merge these to include all unique directives.

```text
Left
```
using System;
using System.Collections.Generic;

```

Base
```
using System;

```

Right
```
using System;
using System.IO;

```

```

--------------------------------

### Define Signatures for AST Nodes

Source: https://mergiraf.org/print.html

Defines signatures for various node types by specifying the node type and the paths to the descendants that form the key.

```rust
signature("using_directive", vec![vec![]]),
signature("field_declaration", vec![vec![Field("name")]]),
signature("method_declaration", vec![
    vec![Field("name")],
    vec![Field("parameters"), ChildType("parameter"), Field("type")]
]),
```

--------------------------------

### Replay changes on moved code in Rust

Source: https://mergiraf.org/print.html

Shows how Mergiraf tracks changes to a boolean expression even after it has been extracted into a new method.

```rust
__
impl Lawnmower {
    fn find_home_station(&self) -> Option<&Station> {
        self.neighbouring_stations().iter().find(|station| {
            self.is_suitable_home(station)
        })
    }

    fn is_suitable_home(&self, station: &Station) -> bool {
        station.id == self.home_station_id
            && !station.occupied
            && station.color == StationColor::Red
    }
}
```

```rust
__
impl Lawnmower {
    fn find_home_station(&self) -> Option<&Station> {
        self.neighbouring_stations().iter().find(|station| {
            station.id == "home"
                && !station.occupied
                && station.color == StationColor::Red
        })
    }
}
```

```rust
__
impl Lawnmower {
    fn find_home_station(&self) -> Option<&Station> {
        self.neighbouring_stations().iter().find(|station| {
            station.id == "home"
                && !station.occupied
                && station.color == StationColor::Blue
        })
    }
}
```

```rust
__
impl Lawnmower {
    fn find_home_station(&self) -> Option<&Station> {
        self.neighbouring_stations().iter().find(|station| {
            self.is_suitable_home(station)
        })
    }

    fn is_suitable_home(&self, station: &Station) -> bool {
        station.id == self.home_station_id
            && !station.occupied
            && station.color == StationColor::Blue
    }
}
```

--------------------------------

### Syntax Tree Representation

Source: https://mergiraf.org/adding-a-language/enabling-commutative-merging.html

The output of parsing a C# file, showing the hierarchical structure of the code as a syntax tree. This visualization is key to identifying nodes like 'using_directive'.

```text
└compilation_unit
  ├using_directive
  │ ├using
  │ ├identifier System
  │ └;
  ├using_directive
  │ ├using
  │ ├qualified_name
  │ │ ├qualifier: qualified_name
  │ │ │ ├qualifier: identifier System
  │ │ │ ├.
  │ │ │ └name: identifier Collections
  │ │ ├.
  │ │ └name: identifier Generic
  │ └;
  ├using_directive
  │ ├using
  │ ├qualified_name
  │ │ ├qualifier: identifier System
  │ │ ├.
  │ │ └name: identifier IO
  │ └;
  └namespace_declaration
    ├namespace
    ├name: identifier HelloWorld
    └body: declaration_list
      ├{
      ├class_declaration
      │ ├modifier
      │ │ └public
      │ ├class
      │ ├name: identifier SomeName
      │ └body: declaration_list
      │   ├{
      │   └}
      └}

```

--------------------------------

### Resolve C function signature conflicts

Source: https://mergiraf.org/conflicts.html

Demonstrates independent changes to function return types and argument types being merged automatically.

```c
void notify_attendees(long status_code);
```

```c
void notify_attendees(int status_code);
```

```c
int notify_attendees(int status_code);
```

```c
int notify_attendees(long status_code);
```

--------------------------------

### Enable diff3 conflict style

Source: https://mergiraf.org/usage.html

Configures Git to use the diff3 conflict style, which is recommended for all Mergiraf workflows.

```gitconfig
[merge]
    conflictStyle = "diff3"
```

```bash
$ git config --global merge.conflictStyle diff3
```

--------------------------------

### Resolve HTML attribute conflicts

Source: https://mergiraf.org/print.html

Demonstrates merging independent attribute additions in an HTML tag using commutative parent configuration.

```html
__
<input type="text" autocomplete="off" />
```

```html
__
<input type="text" />
```

```html
__
<input type="text" value="hello" />
```

```html
__
<input type="text" autocomplete="off" value="hello" />
```

--------------------------------

### Configure Custom Separators for Groups

Source: https://mergiraf.org/print.html

Specifies custom separators for individual children groups within a commutative parent configuration.

```rust
__
CommutativeParent::new("declaration_list", "{", "\n\n", "}")
    .restricted_to(vec![
        ChildrenGroup::with_separator(&["using_directive"], "\n"),
        ChildrenGroup::new(&["namespace_declaration"]),
        ChildrenGroup::new(&["global_attribute"]),
    ]),
```

--------------------------------

### Add Tree-sitter Parser Dependency

Source: https://mergiraf.org/adding-a-language.html

Add the required tree-sitter crate to the dependencies section of Cargo.toml.

```toml
[dependencies]
tree-sitter-csharp = "0.21.3"
```

--------------------------------

### Register Mergiraf as a Git merge driver

Source: https://mergiraf.org/usage.html

Configures the Git merge driver settings globally to use Mergiraf for merge operations.

```gitconfig
[merge "mergiraf"]
    name = mergiraf
    driver = mergiraf merge --git %O %A %B -s %S -x %X -y %Y -p %P -l %L
```

```bash
$ git config --global merge.mergiraf.name mergiraf
$ git config --global merge.mergiraf.driver 'mergiraf merge --git %O %A %B -s %S -x %X -y %Y -p %P -l %L'
```

--------------------------------

### Select Commutative Nodes with Tree-sitter

Source: https://mergiraf.org/print.html

A tree-sitter query to identify specific nodes, such as Python's __all__ lists, that should be treated as commutative.

```query
__
(expression_statement (assignment
  left: (identifier) @variable (#eq? @variable "__all__")
  right: (list) @commutative
))
```

--------------------------------

### Resolve Conflicts Automatically

Source: https://mergiraf.org/usage.html

Use Mergiraf to solve conflicts in a file and inspect the resulting output.

```bash
$ git merge origin/main
Auto-merging config.yml
CONFLICT (content): Merge conflict in config.yml
Automatic merge failed; fix conflicts and then commit the result.
$ cat config.yml
<<<<<<< HEAD
restaurant:
  tasks:
    plates: 1
    bowls: 2
||||||| 15b798c
tasks:
  plates: 1
  bowls: 2
=======
tasks:
  plates: 1
  bowls: 4
>>>>>>> origin/main
```

```bash
$ mergiraf solve config.yml
Solved 1 conflict(s)
```

```yaml
restaurant:
  tasks:
    plates: 1
    bowls: 4
```

--------------------------------

### Debug Tests with Rust Integration Tests

Source: https://mergiraf.org/print.html

Use the integration test file to target a specific directory for debugging within an IDE.

```rust
// use this test to debug a specific test case by changing the path in it.
#[test]
fn debug_test() {
    run_test_from_dir(Path::new("examples/go/working/remove_and_add_imports"))
}
```

--------------------------------

### Resolve Java class attribute additions

Source: https://mergiraf.org/conflicts.html

Shows how Mergiraf merges non-conflicting additions of class attributes in Java.

```java
class Bird {
    String species;
    int weight;
}
```

```java
class Bird {
    String species;
}
```

```java
class Bird {
    String species;
    double wingspan;
}
```

```java
class Bird {
    String species;
    int weight;
    double wingspan;
}
```

--------------------------------

### Define Commutative Parent using Tree-sitter Query

Source: https://mergiraf.org/adding-a-language/enabling-commutative-merging.html

Use `CommutativeParent::from_query` with a tree-sitter query to define commutative parents based on more complex contextual patterns. The `@commutative` capture identifies the node to be treated as commutative.

```tree-sitter query
(expression_statement (assignment
  left: (identifier) @variable (#eq? @variable "__all__")
  right: (list) @commutative
))
```

```rust
CommutativeParent::from_query(
  r#"(expression_statement (assignment
     left: (identifier) @variable (#eq? @variable "__all__")
     right: (list) @commutative)
  )"#, 
  "[", ", ", "]",
)
```

--------------------------------

### Replaying Changes on Moved Code Sections

Source: https://mergiraf.org/conflicts.html

Mergiraf can replay changes from one branch onto a code section that has been moved in another. This requires access to base, left, and right revisions.

```rust
impl Lawnmower {
    fn find_home_station(&self) -> Option<&Station> {
        self.neighbouring_stations().iter().find(|station| {
            self.is_suitable_home(station)
        })
    }

    fn is_suitable_home(&self, station: &Station) -> bool {
        station.id == self.home_station_id
            && !station.occupied
            && station.color == StationColor::Red
    }
}
```

```rust
impl Lawnmower {
    fn find_home_station(&self) -> Option<&Station> {
        self.neighbouring_stations().iter().find(|station| {
            station.id == "home"
                && !station.occupied
                && station.color == StationColor::Red
        })
    }
}
```

```rust
impl Lawnmower {
    fn find_home_station(&self) -> Option<&Station> {
        self.neighbouring_stations().iter().find(|station| {
            station.id == "home"
                && !station.occupied
                && station.color == StationColor::Blue
        })
    }
}
```

```rust
impl Lawnmower {
    fn find_home_station(&self) -> Option<&Station> {
        self.neighbouring_stations().iter().find(|station| {
            self.is_suitable_home(station)
        })
    }

    fn is_suitable_home(&self, station: &Station) -> bool {
        station.id == self.home_station_id
            && !station.occupied
            && station.color == StationColor::Blue
    }
}
```

--------------------------------

### Resolve HTML attribute conflicts

Source: https://mergiraf.org/conflicts.html

Demonstrates merging of attributes in self-closing tags where order is irrelevant.

```html
<input type="text" autocomplete="off" />
```

```html
<input type="text" />
```

```html
<input type="text" value="hello" />
```

```html
<input type="text" autocomplete="off" value="hello" />
```

--------------------------------

### Debug Test Case

Source: https://mergiraf.org/adding-a-language/testing.html

Use the Rust integration test to debug specific test cases with an IDE.

```rust
// use this test to debug a specific test case by changing the path in it.
#[test]
fn debug_test() {
    run_test_from_dir(Path::new("examples/go/working/remove_and_add_imports"))
}
```

--------------------------------

### Manually invoke Mergiraf after Git conflict

Source: https://mergiraf.org/print.html

Use this command sequence when a Git operation results in a merge conflict that requires manual resolution via Mergiraf.

```bash
➜  repo git:(refactor) ✗ git rebase master                                                     Auto-merging src/lawnmower.rs                                                                  CONFLICT (content): Merge conflict in src/lawnmower.rs                                         error: could not apply 162e8a1... Refactor and max_speed                                       hint: Resolve all conflicts manually, mark them as resolved with                               hint: "git add/rm <conflicted_files>", then run "git rebase --continue".                       hint: You can instead skip this commit: run "git rebase --skip".                               hint: To abort and get back to the state before "git rebase", run "git rebase --abort".        hint: Disable this message with "git config advice.mergeConflict false"                        Recorded preimage for 'src/lawnmower.rs'                                                       Could not apply 162e8a1... Refactor and max_speed                                              ➜  repo git:(fc19ba6) ✗ vim src/lawnmower.rs                                                   ➜  repo git:(fc19ba6) ✗ mergiraf solve src/lawnmower.rs
```

--------------------------------

### Merge Conflict Scenario: Base Revision

Source: https://mergiraf.org/architecture.html

Represents the base state of the code before modifications.

```cpp

__
dismountTire(&wheel);
applyGlueAroundPuncture(&wheel.innerTube);
wait(Duration::minutes(2));
applyPatch(&wheel.innerTube);
```

--------------------------------

### Define Commutative Parent in Language Profile

Source: https://mergiraf.org/print.html

Configuration snippet to declare a node type as a commutative parent within the language profile.

```rust
LangProfile {
    commutative_parents: vec![
        CommutativeParent::without_delimiters("compilation_unit", "\n"),
    ],
    ..
},
```

--------------------------------

### JSON Commutative Merge Conflict Resolution

Source: https://mergiraf.org/conflicts.html

Mergiraf detects and reports conflicts when Git's line-based merging results in duplicate keys in commutative structures like JSON. This requires Mergiraf's signature mechanism.

```json
{
    "new_letter": "left value",
    "alpha": "α",
    "beta": "β",
    "gamma": "γ",
    "delta": "δ"
}
```

```json
{
    "alpha": "α",
    "beta": "β",
    "gamma": "γ",
    "delta": "δ"
}
```

```json
{
    "alpha": "α",
    "beta": "β",
    "gamma": "γ",
    "delta": "δ",
    "new_letter": "right value"
}
```

```json
{
    "new_letter": "left value",
    "alpha": "α",
    "beta": "β",
    "gamma": "γ",
    "delta": "δ",
    "new_letter": "right value"
}
```

```json
{
<<<<<<< LEFT
    "new_letter": "left value",
||||||| BASE
=======
    "new_letter": "right value",
>>>>>>> RIGHT
    "alpha": "α",
    "beta": "β",
    "gamma": "γ",
    "delta": "δ"
}
```

--------------------------------

### Define Commutative Parent by Node Type

Source: https://mergiraf.org/adding-a-language/enabling-commutative-merging.html

Use `CommutativeParent::new` to specify a node type and its delimiters for commutative behavior. This is useful for simple cases where the node type alone defines commutativity.

```rust
CommutativeParent::new("declaration_list", "{", "\n\n", "}")
```
Tokens:
Raw