Dogfood Testing.

[sageserpent-open]

What is says on the tin (presumably of dog food).

Use Kinetic Merge on real codebases; raise tickets for bugs or strange-looking merges.

Please don't add issues directly to this ticket. Lots of little flea tickets are far better. 😄

Adding the bug and dogfood labels to your ticket will help categorize it too.

[sageserpent-open]

Suggestion for testing - clone a local repository using git clone --no-hardlinks <local repository> <throwaway sandpit repository>.

Use the --no-commit flag when running Kinetic Merge if you're feeling especially cautious.

Kinetic Merge uses the Git Porcelain and a bit of Git Plumbing, so it shouldn't wreck a repository, but it's good to be careful. Also, somebody might forget the --no-commit flag when using Kinetic Merge, then do a push...

Using clone resets the origin, so there's some damage limitation if bad changes are pushed - they only go as far as the local repository, so git reset --hard etc can be used to rollback.

[sageserpent-open]

Installation:

curl -LJO --verbose http://github.com/sageserpent-open/kineticMerge/releases/download/v<RELEASE VERSION FROM GITHUB>/kinetic-merge

chmod ug+x kinetic-merge

Put kinetic-merge on your shell's path.

If you're on Windows, instead of kinetic-merge use the companion download kinetic-merge.bat and put that on your shell's path.

[sageserpent-open]

(Version 0.1.10)

There is now an optional --match-threshold flag that specifies what fraction of a file's size a section of content has to be, to be detected as part of a code motion match. Pass in a fraction between zero and one, or specify a percentage:

--match-threshold=0.1
--match-threshold=10%.

You can also write:

--match-threshold=10 in the same manner as for Git diff / merge.

Try some variations out, at time of writing, this can have quite profound effects on the merge results.

[sageserpent-open]

(Version 0.2.0)

There is now an optional --minimum-match-size flag that specifies the least amount of content in a file that would be considered for a match.

Unlike --match-threshold, it applies a single limit globally across all files examined by the merge.

If the amount of content to consider for a match in a file via --match-threshold would be less than --minimum-match-size, then the latter takes precedence. However, --match-threshold can be used to set a higher size of matches if desired, on a per-file basis.

--match-threshold defaults to zero, thus handing over entirely to --minimum-match-size. That in turn has a default of 4.

[sageserpent-open]

To hear the application mumbling to itself as it performs a merge, run with the Java system property: -Dlogback-root-level=DEBUG.

You can do this on the command line like so:

kinetic-merge -J-Dlogback-root-level=DEBUG.

Note the -J prefix!

[sageserpent-open]

(Version 0.2.2)

Working in a corporate environment where arbitrary downloads off the Internet are not the done thing?

Your organisation may however permit referencing Maven Central artifacts in Java projects - or at least allow requests for an an artifact in Maven Central together with its transitive dependencies to be staged into its own mirror repository for Maven.

EDIT: if you have Coursier installed, skip the rest of this and go to the next comment...

If so, try this (but not on the day you release to production, though)...

1. Copy this minimal Maven setup to some scratch directory as <path to your scratch directory>/pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.example</groupId>
    <artifactId>useKineticMergeInCorporateEnvironment</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>14</maven.compiler.source>
        <maven.compiler.target>14</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>com.sageserpent</groupId>
            <artifactId>kinetic-merge_3</artifactId>
            <version>0.2.3</version>
        </dependency>
    </dependencies>

    <build>
        <pluginManagement>
            <plugins>
                <plugin>
                    <groupId>com.github.johnpoth</groupId>
                    <artifactId>jshell-maven-plugin</artifactId>
                    <version>1.4</version>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>

</project>

This uses the nice jshell-maven-plugin to allow JShell to be run from Maven, augmented with the classpath of the artifact for Kinetic Merge v0.2.3 (change the dependency as appropriate to track the latest version).

2. From the command line running in whatever Git repository you want to run the merge in, run mvn -f <path to your scratch directory>/pom.xml jshell:run to bring up a classpath-augmented JShell...
3. Now you can execute Kinetic Merge as an embedded library...
4. import com.sageserpent.kineticmerge.Main;
5. Main.apply("--version"); // kinetic-merge 0.2.3
6. Main.apply("--help"); // Help text...
7. Main.apply("--no-commit", "left-bank"); // Merge branch left-bank...
8. Exit JShell: /exit.

[sageserpent-open]

A better alternative if you can't download the executable but a) have access to Maven Central / a mirror repository based off Maven Central and b) have a recent version of Coursier, say 2.1.8, is to use Coursier:

cs launch com.sageserpent::kinetic-merge:0.2.3 -- --no-commit left-bank // Merge branch left-bank...

[sageserpent-open]

(Version 0.2.23)

Kinetic Merge now merges more quickly - gone from 3 minutes to 47 seconds for the example dealt with in issue #25.

[sageserpent-open]

Really can't download any kind of script / JAR / executable?

Fear not, you can build it from scratch - clone this repository (or grab a source drop) from GitHub, then run sbt packageExecutable in the top level of the directory you've cloned / downloaded - that will place a freshly baked executable and companion Windows batch file in the target directory.