+ * Examples (git is a {@link Git} instance):
+ *
+ * Check out an existing branch: + * + *
+ * git.checkout().setName("feature").call();
+ *
+ * + * Check out paths from the index: + * + *
+ * git.checkout().addPath("file1.txt").addPath("file2.txt").call();
+ *
+ * + * Check out a path from a commit: + * + *
+ * git.checkout().setStartPoint("HEADˆ").addPath("file1.txt").call();
+ *
+ *
+ * + * Create a new branch and check it out: + * + *
+ * git.checkout().setCreateBranch(true).setName("newbranch").call();
+ *
+ * + * Create a new tracking branch for a remote branch and check it out: + * + *
+ * git.checkout().setCreateBranch(true).setName("stable")
+ * .setUpstreamMode(SetupUpstreamMode.SET_UPSTREAM)
+ * .setStartPoint("origin/stable").call();
+ *
*
* @see
+ * If this option is set, neither the {@link #setCreateBranch(boolean)} nor
+ * {@link #setName(String)} option is considered. In other words, these
+ * options are exclusive.
+ *
* @param path
- * Path to update in the working tree and index.
+ * path to update in the working tree and index
* @return {@code this}
*/
public CheckoutCommand addPath(String path) {
@@ -252,14 +294,19 @@ public CheckoutCommand addPath(String path) {
}
/**
- * Set whether to checkout all paths
+ * Set whether to checkout all paths.
* * This options should be used when you want to do a path checkout on the * entire repository and so calling {@link #addPath(String)} is not possible * since empty paths are not allowed. + *
+ * If this option is set, neither the {@link #setCreateBranch(boolean)} nor
+ * {@link #setName(String)} option is considered. In other words, these
+ * options are exclusive.
*
* @param all
- * true to checkout all paths, false otherwise
+ * true to checkout all paths, false
+ * otherwise
* @return {@code this}
* @since 2.0
*/
@@ -361,8 +408,20 @@ private void processOptions() throws InvalidRefNameException {
}
/**
+ * Specify the name of the branch or commit to check out, or the new branch
+ * name.
+ *
+ * When only checking out paths and not switching branches, use + * {@link #setStartPoint(String)} or {@link #setStartPoint(RevCommit)} to + * specify from which branch or commit to check out files. + *
+ * When {@link #setCreateBranch(boolean)} is set to true, use
+ * this method to set the name of the new branch to create and
+ * {@link #setStartPoint(String)} or {@link #setStartPoint(RevCommit)} to
+ * specify the start point of the branch.
+ *
* @param name
- * the name of the new branch
+ * the name of the branch or commit
* @return this instance
*/
public CheckoutCommand setName(String name) {
@@ -372,6 +431,14 @@ public CheckoutCommand setName(String name) {
}
/**
+ * Specify whether to create a new branch.
+ *
+ * If true is used, the name of the new branch must be set
+ * using {@link #setName(String)}. The commit at which to start the new
+ * branch can be set using {@link #setStartPoint(String)} or
+ * {@link #setStartPoint(RevCommit)}; if not specified, HEAD is used. Also
+ * see {@link #setUpstreamMode} for setting up branch tracking.
+ *
* @param createBranch
* if true a branch will be created as part of the
* checkout and set to the specified start point
@@ -384,6 +451,8 @@ public CheckoutCommand setCreateBranch(boolean createBranch) {
}
/**
+ * Specify to force the ref update in case of a branch switch.
+ *
* @param force
* if true and the branch with the given name
* already exists, the start-point of an existing branch will be
@@ -398,9 +467,16 @@ public CheckoutCommand setForce(boolean force) {
}
/**
+ * Set the name of the commit that should be checked out.
+ *
+ * When checking out files and this is not specified or null,
+ * the index is used.
+ *
+ * When creating a new branch, this will be used as the start point. If not
+ * specified or null, the current HEAD is used.
+ *
* @param startPoint
- * corresponds to the start-point option; if null,
- * the current HEAD will be used
+ * commit name to check out
* @return this instance
*/
public CheckoutCommand setStartPoint(String startPoint) {
@@ -411,9 +487,16 @@ public CheckoutCommand setStartPoint(String startPoint) {
}
/**
+ * Set the commit that should be checked out.
+ *
+ * When creating a new branch, this will be used as the start point. If not
+ * specified or null, the current HEAD is used.
+ *
+ * When checking out files and this is not specified or null,
+ * the index is used.
+ *
* @param startCommit
- * corresponds to the start-point option; if null,
- * the current HEAD will be used
+ * commit to check out
* @return this instance
*/
public CheckoutCommand setStartPoint(RevCommit startCommit) {
@@ -424,6 +507,9 @@ public CheckoutCommand setStartPoint(RevCommit startCommit) {
}
/**
+ * When creating a branch with {@link #setCreateBranch(boolean)}, this can
+ * be used to configure branch tracking.
+ *
* @param mode
* corresponds to the --track/--no-track options; may be
* null
@@ -437,7 +523,7 @@ public CheckoutCommand setUpstreamMode(
}
/**
- * @return the result
+ * @return the result, never null
*/
public CheckoutResult getResult() {
if (status == null)