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

import javax.annotation.Nonnull;

/**
 * A builder which can be used to construct a {@link com.atlassian.bitbucket.mesh.git.builder.GitProcess process}
 * for running {@code git merge}. In addition to {@link GitMergeBuilderSupport common merge options}, this builder
 * provides options for controlling the fast-forwardness of the merge, specifying the commit message and including
 * summary messages in the commit messages to describe the commits which were included in the merge.
 *
 * @see GitSquashMergeBuilder
 */
public interface GitMergeBuilder extends GitMergeBuilderSupport<GitMergeBuilder> {

    /**
     * Sets a flag which, when enabled, causes {@code git merge} to include a brief synopsis of the commits included
     * by the merge. The exact output of this flag varies slightly depending on the version of git installed, but in
     * general it will append summary messages for all commits included by the merged commit which are not already
     * present on the target branch.
     * <p>
     * When {@code git merge --log} is enabled using this method, <i>all</i> commits included in the merge will have
     * their summaries appended. To apply a limit to how many summaries are included, use {@link #log(int)} instead.
     * <p>
     * Note: If a {@link #message(String) message} is supplied, it will become the first part of the commit message
     * for the merge and the {@code --log}-produced summaries will be appended after it.
     *
     * @param value {@code true} to include commit summaries for all merged commits; otherwise, {@code false} (the
     *              default) to use only the provided {@link #message(String) message}
     * @return {@code this}
     */
    @Nonnull
    GitMergeBuilder log(boolean value);

    /**
     * Sets the number of summary messages to append for commits included in the merge. If the provided value is less
     * than or equal to {@code 0}, no summaries will be appended to the merge's commit message. Otherwise, up to the
     * number provided will be included. Included commits begin with the {@link #commit(String) commit} specified as
     * the tip of the merge, traversing from there back through history to older commits until the configured number
     * have been appended or included commits have been exhausted. The exact output from this setting varies slightly
     * depending on the version of git installed, but in general it appends summary messages for commits included by
     * the merged commit which are not already present on the target branch.
     * <p>
     * Note: If a {@link #message(String) message} is supplied, it will become the first part of the commit message
     * for the merge and the {@code --log}-produced summaries will be appended after it.
     *
     * @param value the number of commits to include summaries for in the merge's commit message; for {@code 0} or
     *              negative values, no summaries will be included
     * @return {@code this}
     */
    @Nonnull
    GitMergeBuilder log(int value);

    /**
     * Sets the commit message to be used for the merge.
     * <p>
     * Note: If {@link #log(int)} or {@link #log(boolean)} is used to enable {@code --log}, any message provided here
     * is used as the beginning of the commit message and summaries are appended to it.
     *
     * @param value the commit message for the merge
     * @return {@code this}
     */
    @Nonnull
    GitMergeBuilder message(String value);
}
