diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/CheckoutCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/CheckoutCommand.java index 57f47a496..9d3bf561b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/CheckoutCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/CheckoutCommand.java @@ -83,7 +83,42 @@ import org.eclipse.jgit.treewalk.filter.PathFilterGroup; import org.eclipse.jgit.util.FileUtils; /** - * Checkout a branch to the working tree + * Checkout a branch to the working tree. + *

+ * 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 { } /** + * Add a single path to the list of paths to check out. To check out all + * paths, use {@link #setAllPaths(boolean)}. + *

+ * 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 class CheckoutCommand extends GitCommand { } /** - * 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 @@ public class CheckoutCommand extends GitCommand { } /** + * 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 class CheckoutCommand extends GitCommand { } /** + * 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 class CheckoutCommand extends GitCommand { } /** + * 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 class CheckoutCommand extends GitCommand { } /** + * 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 class CheckoutCommand extends GitCommand { } /** + * 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 class CheckoutCommand extends GitCommand { } /** + * 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 class CheckoutCommand extends GitCommand { } /** - * @return the result + * @return the result, never null */ public CheckoutResult getResult() { if (status == null)