Kintsugi: merge conflict resolution for Xcode project files

The one file that breaks every merge

Kintsugi exists because of a single file. The README names the frustration as one of working with Xcode together with Git, which is resolving conflicts in Xcode project files, that is, the `project.pbxproj` file. The reason that file is special is not documented in detail in the README, but the shape of the problem is easy to recognise from the outside: it is a large machine generated plist that Xcode rewrites whenever you add a file, and it is a single file for the whole project, so two people touching two different files in two different directories still produce a textual conflict in the same blob. Kintsugi sets out to solve exactly this problem, automatically resolving Git merge conflicts occurring in `.pbxproj` files. The stated end goal is worth quoting because it sets the expectation properly, that the tool should succeed 99.9% of the time and let you resolve the real conflicts in a convenient way the rest of the time. The name comes from the Japanese art of repairing broken pottery by mending it with gold, which is an apt description of taking two broken halves of a project file and producing one that holds together.

Diff the changes, reset the conflict, re-apply the changes

The mechanism is short. Kintsugi understands the changes you have made to the `.pbxproj` file, so it simply resets the conflicts and re-applies those changes to it. That is a different strategy from trying to interpret the conflict markers and pick a winner. Instead of reading a broken file and repairing the text, the tool computes the semantic difference between the base version and each side, throws away the conflicted result, and then applies both sets of changes to the base in turn, which is the behaviour you want from a file whose contents are a set of records rather than prose. The implementation depends on another project for this. Kintsugi heavily relies on Xcodeproj, using its diff capability to extract the changes and its project files editing capabilities to apply the changes. That is a sensible dependency to lean on, because parsing and rewriting the pbxproj format is handled by a dedicated library, and a tool that reimplemented the format would be a maintenance liability of its own. The one precondition the README states is that a 3-way merge must be possible, which is what lets the tool know what the base version was.

Running it by hand, and the interactive fallback

The manual usage is one command. When there is a `.pbxproj` file with Git conflicts and a 3-way merge is possible, you run `kintsugi <path_to_pbxproj_file>`, and the README promises that the magic happens. Installation is equally short, either `gem install kintsugi`, or, if you prefer bundler, a line in your Gemfile that reads `gem 'kintsugi', require: false`, with the `require: false` mattering because the tool is a command line program rather than a library your app loads.

The install is one command, or a single line in your Gemfile if you prefer bundler:

$ gem install kintsugi

gem 'kintsugi', require: false

The part that matters in practice is what happens when the tool cannot resolve a conflict by itself. In that case it displays a helpful message describing the conflict and the choices available to resolve it, which is the 99.9% tail the README promised to hand back to you in a convenient form. The interactive prompt can be turned off with the `--interactive-resolution false` flag, which you will want in any environment where nobody is watching the terminal, and the same flag is the one you pass to the merge driver installation when you want the non interactive behaviour everywhere.

Installing itself as a Git merge driver

The interesting deployment is automatic. Kintsugi can be set up to resolve conflicts in pbxproj files when such conflicts occur, and the automatic route is a single command, `kintsugi install-driver`, which installs Kintsugi as a merge driver globally, with the note that Kintsugi needs to be in your PATH. The README attaches a warning to that command in the form of an exclamation mark, and it is worth repeating here: do not install with bundler, because the installation might succeed even if Kintsugi is not in your PATH. That is a nasty failure mode, since a broken merge driver usually surfaces as a confusing error at merge time rather than at install time. You can pass arguments to the install command and they will be passed on to Kintsugi when it runs as a merge driver, which is how you disable interactive resolution for everybody. The manual route is the same thing spelled out: two git config entries naming the driver and its command line with the `%O`, `%A`, `%B` and `%P` placeholders, added with `--global` if you want them for every repository, and then one line in the `.gitattributes` file at the root of the repository, `*.pbxproj merge=kintsugi`, which is what tells Git to route those files through it. The README notes that the gitattributes documentation covers doing this globally.

The other way out: stop committing the project file

The README has an alternatives section, and it is short and pointed. All of the alternatives it lists, XcodeGen, Tuist and Xcake, allow you to generate your Xcode projects based on a spec or a manifest, and the consequence is that you commit those files to git and can even remove the `.xcodeproj` files from git entirely. That is a genuinely different approach rather than a competing implementation of the same one. Kintsugi keeps the project file and makes merging it survivable, which is the right choice when the project file contains things a generator cannot express, when you inherit an existing project, or when the team works on a project whose build settings have grown organically over years. The generator approach removes the conflict surface entirely, which is stronger than making it resolvable, and it costs you a migration and a constraint that everything in the project is expressible in the manifest. Many teams that suffer from pbxproj conflicts have found that the generator route is the better investment, and the README is generous enough to point at the alternatives rather than to claim that merging is the only way.

A small Ruby gem with a real company behind it

The repository is a Ruby gem in the conventional shape, with a `kintsugi.gemspec`, a `Rakefile`, a `Gemfile`, a `.rspec` file for the test framework configuration, a `.rubocop.yml` for style, a `lib/` directory, a `spec/` directory, a `bin/` directory, an `assets/` folder holding the screenshot of the interactive resolution dialog, a `logo/` folder, and a contribution guide. The README badge names the Ruby Style Guide as the code style, which is rubocop, so the project holds to a documented style rather than a personal one. The copyright line reads Lightricks, 2021, with the MIT licence in the repository, and the tool is the kind of small utility that a company publishes because it fixed a problem the whole company had. The release history shows a steady line rather than bursts, with 0.7.8 in October 2024, 0.7.9 in November 2024 and 0.7.10 in September 2026, and the last push was on 2026-09-19. The dependency on Xcodeproj is the thing to watch over time, since the tool's correctness depends on another project understanding the pbxproj format correctly, and pbxproj changes with Xcode.

Editorial conclusion

Adopt Kintsugi if your team commits .xcodeproj files and merges them often enough that the conflicts are a recurring tax, and if you are on a Git workflow where a merge driver is acceptable. Do not adopt it if you can remove the project file from version control instead, because generating the project from a specification solves the problem at its root, and the README lists the tools for that. Before you install the merge driver, read the warning about bundler, because the automatic installer can succeed while leaving the binary off your PATH, which produces a confusing failure at merge time rather than at install time. The licence is MIT, the newest release is 0.7.10 from 2026-09-03, and the last push was on 2026-09-19.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Lightricks/Kintsugi on GitHub
4. README
5. Releases