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

import com.atlassian.bitbucket.mesh.git.builder.GitProcessBuilderSupport;
import com.atlassian.bitbucket.mesh.repository.Repository;

import javax.annotation.Nonnull;
import javax.annotation.Nullable;

/**
 * A type-safe builder for using the {@code git ls-remote} command. This command gives similar results as
 * {@code git for-each-ref} but on {@code git} 2.34 and higher does not fail if the referenced objects do not exist,
 * which is sometimes what we want/need.
 *
 * @since 1.3
 */
public interface GitLsRemoteBuilder extends GitProcessBuilderSupport<GitLsRemoteBuilder> {

    /**
     * @param value if {@code true}, suppresses printing of remote URL to stderr
     * @return the builder
     */
    @Nonnull
    GitLsRemoteBuilder quiet(boolean value);

    /**
     * Specifies the ref patterns to match. Wildcards can be used in the patterns. If no wildcard is set, only exact
     * matches are returned.
     *
     * @param pattern the pattern to match
     * @param morePatterns more patterns to match
     * @return the builder
     */
    @Nonnull
    GitLsRemoteBuilder refs(@Nullable String pattern, @Nullable String... morePatterns);

    /**
     * Specifies the ref patterns to match. Wildcards can be used in the patterns. If no wildcard is set, only exact
     * matches are returned.
     *
     * @param patterns the patterns to match
     * @return the builder
     */
    @Nonnull
    GitLsRemoteBuilder refs(@Nullable Iterable<String> patterns);

    /**
     * @param value {@code true} to set the {@code --refs} flags, which suppresses tag peeling and returning
     *              pseudorefs like HEAD in the output
     * @return the builder
     */
    @Nonnull
    GitLsRemoteBuilder refsOnly(boolean value);

    /**
     * @param repository the (local) repository to run ls-remote against
     * @return the builder
     */
    @Nonnull
    GitLsRemoteBuilder repository(@Nonnull Repository repository);

    /**
     * @param remoteUrl the repository URL to run ls-remote against
     * @return the builder
     */
    @Nonnull
    GitLsRemoteBuilder repository(@Nonnull String remoteUrl);
}
