package com.atlassian.bitbucket.mesh.git.builder.mergetree;

import com.atlassian.bitbucket.mesh.git.builder.GitProcessBuilderSupport;
import com.atlassian.bitbucket.mesh.git.exception.UsageException;

import javax.annotation.Nonnull;

/**
 * A builder for using the {@code git merge-tree} command.
 * <p>
 * The {@code git merge-tree} command support two different modes, {@code --write-tree} and the now deprecated
 * {@code --trivial-merge} mode. This builder only supports {@code --write-tree} and indeed the argument is
 * implicitly passed to the command.
 * <p>
 * <strong>NOTE:</strong> This command is only available when used with Git 2.38+. Attempts to use it on an older
 * version of Git will result in a {@link UsageException} being thrown.
 *
 * @since 2.0
 */
public interface GitMergeTreeBuilder extends GitProcessBuilderSupport<GitMergeTreeBuilder> {

    /**
     * Controls whether {@code git merge-tree} will allow merging two commits that have no common ancestor. The default
     * value is {@code false}.
     *
     * @param value {@code true} to allow merging unrelated commits; otherwise, {@code false} to require commits
     *              to share a common ancestor in order to merge them
     * @return {@code this}
     */
    @Nonnull
    GitMergeTreeBuilder allowUnrelatedHistories(boolean value);

    /**
     * This branch/commit will be merged with that specified by {@link #branch2(String)}.
     * This is a required parameter.
     *
     * @return {@code this}
     */
    @Nonnull
    GitMergeTreeBuilder branch1(@Nonnull String value);

    /**
     * This branch/commit will be merged with that specified by {@link #branch1(String)}.
     * This is a required parameter.
     *
     * @return {@code this}
     */
    @Nonnull
    GitMergeTreeBuilder branch2(@Nonnull String value);

    /**
     * Write any informational messages such as "Auto-merging" or CONFLICT notices to the end of stdout. The
     * default is to include these messages if there are merge conflicts, and to omit them otherwise.
     *
     * @param value {@code true} to write informational messages if there are merge conflicts; otherwise, {@code false}
     *                           to omit them.
     * @return {@code this}
     */
    @Nonnull
    GitMergeTreeBuilder messages(boolean value);

    /**
     * In the Conflicted file info section, instead of writing a list of (mode, oid, stage, path) tuples to output
     * for conflicted files, just provide a list of filenames with conflicts (and do not list filenames multiple times
     * if they have multiple conflicting stages). The default is to include the full output.
     *
     * @param value {@code true} to write names only; otherwise, {@code false} to include names only.
     * @return {@code this}
     */
    @Nonnull
    GitMergeTreeBuilder nameOnly(boolean value);

    /**
     * @param value {@code true} to pass {@code -z} to {@code git merge-tree}; otherwise, {@code false}
     * @return {@code this}
     */
    @Nonnull
    GitMergeTreeBuilder nullTerminated(boolean value);
}
