package com.atlassian.bitbucket.repository.sync;

/**
 * Enumerates possible actions which may be performed to bring an {@link RejectedRef out-of-sync} ref back in sync
 * with its upstream. These actions are performed manually when a ref can no longer be automatically synchronized.
 * @see RefSyncService#synchronize(RefSyncRequest)
 */
public enum RefSyncAction {

    /**
     * Synchronizes the ref by discarding the local changes in favour of the upstream changes.
     * <p>
     * The exact behaviour of this action depends on the {@link RejectedRef ref}'s {@link RejectedRefState state}:
     * <ul>
     *     <li>{@link RejectedRefState#AHEAD Ahead} and {@link RejectedRefState#DIVERGED diverged} refs are
     *     <i>overwritten</i> with the same commit as upstream</li>
     *     <li>{@link RejectedRefState#ORPHANED Orphaned} refs are <i>deleted</i></li>
     * </ul>
     */
    DISCARD,
    /**
     * Synchronizes the ref by merging in upstream changes, producing a new merge commit. This action is only available
     * for {@link RejectedRefState#DIVERGED diverged} refs. Refs which are {@link RejectedRefState#AHEAD ahead} or
     * {@link RejectedRefState#ORPHANED} are already up-to-date with every commit available upstream, meaning there
     * is nothing to merge. Additionally, merge is never available for {@link RejectedRef#isTag() tags}.
     * <p>
     * Context options:
     * <ul>
     *     <li><b>"commitMessage"</b> - Defines the commit message for the merge</li>
     * </ul>
     *
     * @see RefAlreadySynchronizedException
     */
    MERGE,
}
