package com.atlassian.bitbucket.scm.git.command.merge;

import com.atlassian.bitbucket.scm.git.command.GitCommand;

import javax.annotation.Nonnull;

/**
 * A builder which can be used to construct a {@link GitCommand command} for running
 * {@code git merge --squash}. This builder only supports the {@link GitMergeBuilderSupport common merge options}.
 * @see GitMergeBuilder
 */
public interface GitSquashMergeBuilder extends GitMergeBuilderSupport<GitSquashMergeBuilder> {

    /**
     * Sets the fast-forward mode to use when executing {@code git merge}. The modes available are documented on the
     * enumeration and have different behaviour when applied to {@code --squash} merges:
     * <ul>
     *     <li>{@link GitMergeFastForward#OFF --no-ff} and {@link GitMergeFastForward#ON --ff} are both ignored
     *     <ul>
     *         <li>{@code --ff} is accepted by {@code git merge --squash} but does not change its behaviour</li>
     *         <li>{@code --no-ff} causes {@code git merge --squash} to fail but mimics the behaviour of a squash
     *         merge, which always produces a new commit, and so it is ignored by this builder</li>
     *     </ul></li>
     *     <li>{@link GitMergeFastForward#ONLY --ff-only} when paired with {@code --squash} <i>still creates a new
     *     commit</i>, but will fail if the source branch is not fast-forward from the target rather than actually
     *     performing any merging</li>
     * </ul>
     *
     * @param value the fast-forward mode to apply when performing the merge; only {@link GitMergeFastForward#ONLY
     *              --ff-only} has distinct behaviour
     * @return {@code this}
     */
    @Nonnull
    @Override
    GitSquashMergeBuilder ff(GitMergeFastForward value);
}
