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

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

import javax.annotation.Nonnull;

/**
 * A type-safe, argument-safe builder for {@code git ls-tree}.
 */
public interface GitLsTreeBuilder extends GitCommandBuilderSupport<GitLsTreeBuilder> {

    /**
     * @param value {@code true} to pass {@code -z} to {@code git ls-tree}; otherwise, {@code false}
     * @return {@code this}
     * @since 4.2
     */
    @Nonnull
    GitLsTreeBuilder nullTerminated(boolean value);

    /**
     * @param value {@code true} to pass {@code -r} to {@code git ls-tree}; otherwise, {@code false}
     * @return {@code this}
     */
    @Nonnull
    GitLsTreeBuilder recursive(boolean value);

    /**
     * @param value {@code true} to pass {@code -l} to {@code git ls-tree}; otherwise, {@code false}
     * @return {@code this}
     * @since 4.2
     */
    @Nonnull
    GitLsTreeBuilder sizes(boolean value);

    /**
     * @param value the {@code tree-ish} (typically a {@code commit} or {@code tree} by ref name or SHA-1)
     *              to pass to {@code git ls-tree}
     * @return {@code this}
     */
    @Nonnull
    GitLsTreeBuilder tree(@Nonnull String value);

    /**
     * Offers a convenient shorthand for identifying a subtree in a given commit. For example, passing
     * {@code ("master", "src/main/java")} will output the contents of the {@code src/main/java} tree
     * on the "master" branch. Note that passing "master:src/main/java" to {@link #tree(String)} would
     * produce the same output.
     *
     * @param rev  the commit to display the tree at, identified by ref name or SHA-1
     * @param file the path of the tree to display, which may be {@code ""} to display the root tree
     * @return {@code this}
     */
    @Nonnull
    GitLsTreeBuilder tree(@Nonnull  String rev, @Nonnull  String file);
}
