package com.atlassian.bitbucket.mesh.git.submodule;

import com.atlassian.bitbucket.mesh.repository.Repository;

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

/**
 * Provides access to a repository's {@link Submodules}.
 */
public interface SubmoduleManager {

    /**
     * Retrieves {@link Submodules} for the provided repository at the specified commit, optionally limited to
     * a specific base path.
     * <p>
     * Since {@code .gitmodules} is committed to the repository, the submodules the repository has can change
     * from commit to commit.
     * <p>
     * If a {@code basePath} is provided {@link Submodules#get} will treat provided paths as relative to the
     * base path during lookups, and the returned {@link Submodule} instances will likewise use relative
     * paths. Otherwise, if no {@code basePath} is provided, submodules must be looked up using their <i>full
     * paths</i>, and the returned {@link Submodule}s will likewise have full paths.
     *
     * @param repository the repository to retrieve submodules for
     * @param commitId   the commit to retrieve submodules at
     * @param basePath   an optional base path, to allow using relative paths when {@link Submodules#get looking
     *                   up submodules}
     * @return the repository's configured submodules
     */
    @Nonnull
    Submodules get(@Nonnull Repository repository, @Nonnull String commitId, @Nullable String basePath);
}
