org.eclipse.jgit.api

Class CheckoutCommand

java.lang.Object

org.eclipse.jgit.api.GitCommand<Ref>

org.eclipse.jgit.api.CheckoutCommand

All Implemented Interfaces:

Callable<Ref>

public class CheckoutCommand
extends GitCommand<Ref>

Checkout a branch to the working tree.

Examples (git is a 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 Also:

Git documentation about Checkout

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CheckoutCommand.Stage Stage to check out, see setStage(Stage).

Field Summary

Fields inherited from class org.eclipse.jgit.api.GitCommand

repo

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	CheckoutCommand(Repository repo)

Method Summary

Methods

Modifier and Type	Method and Description
CheckoutCommand	addPath(String path) Add a single slash-separated path to the list of paths to check out.
Ref	call() Executes the command
protected CheckoutCommand	checkoutPaths() Checkout paths into index and working directory
CheckoutResult	getResult()
CheckoutCommand	setAllPaths(boolean all) Set whether to checkout all paths.
CheckoutCommand	setCreateBranch(boolean createBranch) Specify whether to create a new branch.
CheckoutCommand	setForce(boolean force) Specify to force the ref update in case of a branch switch.
CheckoutCommand	setName(String name) Specify the name of the branch or commit to check out, or the new branch name.
CheckoutCommand	setOrphan(boolean orphan) Specify whether to create a new orphan branch.
CheckoutCommand	setStage(CheckoutCommand.Stage stage) When checking out the index, check out the specified stage (ours or theirs) for unmerged paths.
CheckoutCommand	setStartPoint(RevCommit startCommit) Set the commit that should be checked out.
CheckoutCommand	setStartPoint(String startPoint) Set the name of the commit that should be checked out.
CheckoutCommand	setUpstreamMode(CreateBranchCommand.SetupUpstreamMode mode) When creating a branch with setCreateBranch(boolean), this can be used to configure branch tracking.

Methods inherited from class org.eclipse.jgit.api.GitCommand

checkCallable, getRepository, setCallable

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CheckoutCommand

protected CheckoutCommand(Repository repo)

Parameters:

repo -

Method Detail

call

public Ref call()
         throws GitAPIException,
                RefAlreadyExistsException,
                RefNotFoundException,
                InvalidRefNameException,
                CheckoutConflictException

Description copied from class: GitCommand

Executes the command

Specified by:

call in interface Callable<Ref>

Specified by:

call in class GitCommand<Ref>

Returns:

the newly created branch

Throws:

RefAlreadyExistsException - when trying to create (without force) a branch with a name that already exists

RefNotFoundException - if the start point or branch can not be found

InvalidRefNameException - if the provided name is null or otherwise invalid

CheckoutConflictException - if the checkout results in a conflict

GitAPIException - or subclass thereof when an error occurs

addPath

public CheckoutCommand addPath(String path)

Add a single slash-separated path to the list of paths to check out. To check out all paths, use setAllPaths(boolean).

If this option is set, neither the setCreateBranch(boolean) nor setName(String) option is considered. In other words, these options are exclusive.

Parameters:

path - path to update in the working tree and index (with / as separator)

Returns:

this

setAllPaths

public CheckoutCommand setAllPaths(boolean all)

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 addPath(String) is not possible since empty paths are not allowed.

If this option is set, neither the setCreateBranch(boolean) nor setName(String) option is considered. In other words, these options are exclusive.

Parameters:

all - true to checkout all paths, false otherwise

Returns:

this

Since:

2.0

checkoutPaths

protected CheckoutCommand checkoutPaths()
                                 throws IOException,
                                        RefNotFoundException

Checkout paths into index and working directory

Returns:

this instance

Throws:

IOException

RefNotFoundException

setName

public CheckoutCommand setName(String name)

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 setStartPoint(String) or setStartPoint(RevCommit) to specify from which branch or commit to check out files.

When setCreateBranch(boolean) is set to true, use this method to set the name of the new branch to create and setStartPoint(String) or setStartPoint(RevCommit) to specify the start point of the branch.

Parameters:

name - the name of the branch or commit

Returns:

this instance

setCreateBranch

public CheckoutCommand setCreateBranch(boolean createBranch)

Specify whether to create a new branch.

If true is used, the name of the new branch must be set using setName(String). The commit at which to start the new branch can be set using setStartPoint(String) or setStartPoint(RevCommit); if not specified, HEAD is used. Also see setUpstreamMode(org.eclipse.jgit.api.CreateBranchCommand.SetupUpstreamMode) for setting up branch tracking.

Parameters:

createBranch - if true a branch will be created as part of the checkout and set to the specified start point

Returns:

this instance

setOrphan

public CheckoutCommand setOrphan(boolean orphan)

Specify whether to create a new orphan branch.

If true is used, the name of the new orphan branch must be set using setName(String). The commit at which to start the new orphan branch can be set using setStartPoint(String) or setStartPoint(RevCommit); if not specified, HEAD is used.

Parameters:

orphan - if true a orphan branch will be created as part of the checkout to the specified start point

Returns:

this instance

Since:

3.3

setForce

public CheckoutCommand setForce(boolean force)

Specify to force the ref update in case of a branch switch.

Parameters:

force - if true and the branch with the given name already exists, the start-point of an existing branch will be set to a new start-point; if false, the existing branch will not be changed

Returns:

this instance

setStartPoint

public CheckoutCommand setStartPoint(String startPoint)

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.

Parameters:

startPoint - commit name to check out

Returns:

this instance

setStartPoint

public CheckoutCommand setStartPoint(RevCommit startCommit)

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.

Parameters:

startCommit - commit to check out

Returns:

this instance

setUpstreamMode

public CheckoutCommand setUpstreamMode(CreateBranchCommand.SetupUpstreamMode mode)

When creating a branch with setCreateBranch(boolean), this can be used to configure branch tracking.

Parameters:

mode - corresponds to the --track/--no-track options; may be null

Returns:

this instance

setStage

public CheckoutCommand setStage(CheckoutCommand.Stage stage)

When checking out the index, check out the specified stage (ours or theirs) for unmerged paths.

This can not be used when checking out a branch, only when checking out the index.

Parameters:

stage - the stage to check out

Returns:

this

getResult

public CheckoutResult getResult()

Returns:

the result, never null