org.jboss.forge.addon.git

Interface GitUtils

public interface GitUtils

Forge's wrapper on top of the JGit API.

Most of the JGit operations require too much ceremony: calling a lot of setter methods before doing the real execution. This API encapsulates all the possible parameters as part of the method parameters and does all the setter calls itself.

Author:

Lincoln Baxter, III, Jevgeni Zelenkov

Method Summary

Methods

Modifier and Type	Method and Description
void	add(org.eclipse.jgit.api.Git repo, String filePattern) Stages the files matching the given pattern from the working tree to the GIT index.
void	addAll(org.eclipse.jgit.api.Git repo) Stages all the new, modified and deleted files from the working tree to the GIT index.
org.eclipse.jgit.lib.Ref	checkout(org.eclipse.jgit.api.Git git, org.eclipse.jgit.lib.Ref localRef, org.eclipse.jgit.api.CreateBranchCommand.SetupUpstreamMode mode, boolean force) Checks out an already existing branch.
org.eclipse.jgit.lib.Ref	checkout(org.eclipse.jgit.api.Git git, String remote, boolean createBranch, org.eclipse.jgit.api.CreateBranchCommand.SetupUpstreamMode mode, boolean force) Checks out or creates a given GIT branch.
void	cherryPick(org.eclipse.jgit.api.Git repo, org.eclipse.jgit.lib.Ref commit) Cherry-picks a given commit to the current HEAD.
org.eclipse.jgit.api.CherryPickResult	cherryPickNoMerge(org.eclipse.jgit.api.Git git, org.eclipse.jgit.lib.Ref commit) Does the same as the original cherry-pick except committing after running merger.
org.eclipse.jgit.api.Git	clone(DirectoryResource dir, String repoUri) Clones a GIT repository.
void	close(org.eclipse.jgit.api.Git repo) Closes the resources and decrements the use count of the given repository.
void	commit(org.eclipse.jgit.api.Git repo, String message) Creates a new commit with the current contents of the index along with a log message.
void	commitAll(org.eclipse.jgit.api.Git repo, String message) Stages all the new, modified and deleted files to the index and creates a commit from its current contents.
org.eclipse.jgit.lib.Ref	createBranch(org.eclipse.jgit.api.Git git, String branchName) Creates a new branch in the given GIT repository and checks it out.
org.eclipse.jgit.transport.FetchResult	fetch(org.eclipse.jgit.api.Git git, String remote, String refSpec, int timeout, boolean fsck, boolean dryRun, boolean thin, boolean prune) Fetches the Git objects from a remote repository.
String	getCurrentBranchName(org.eclipse.jgit.api.Git repo) Returns the name of the branch that is currently checked out in the given repository.
List<org.eclipse.jgit.lib.Ref>	getLocalBranches(org.eclipse.jgit.api.Git repo) Returns all the local branches of a given GIT repository.
List<String>	getLogForBranch(org.eclipse.jgit.api.Git repo, String branchName) Returns a list of the messages of all the commits for a given branch.
List<String>	getLogForCurrentBranch(org.eclipse.jgit.api.Git repo) Returns a list of the messages of all the commits in the current branch.
List<org.eclipse.jgit.lib.Ref>	getRemoteBranches(org.eclipse.jgit.api.Git repo) Returns all the remote branches of a given GIT repository.
org.eclipse.jgit.api.Git	git(DirectoryResource dir) Returns a handle to an existing Git repository.
org.eclipse.jgit.api.Git	init(DirectoryResource dir) Initializes a new GIT repository.
org.eclipse.jgit.api.PullResult	pull(org.eclipse.jgit.api.Git git, int timeout) Pulls the latest changes from the remote repository and incorporates them into the given one.
void	resetHard(org.eclipse.jgit.api.Git repo, String newBase) Resets the HEAD, the index and the working tree to point to the given commit.
void	stashApply(org.eclipse.jgit.api.Git repo, String... stashRef) Applies the changes in a stashed commit to the working directory and index.
void	stashCreate(org.eclipse.jgit.api.Git repo) Stashes the contents on the working directory and index in separate commits and resets to the current HEAD commit.
void	stashDrop(org.eclipse.jgit.api.Git repo) Drops the last stashed commit.
org.eclipse.jgit.lib.Ref	switchBranch(org.eclipse.jgit.api.Git repo, String branchName) Changes the currently checked out branch of a given repository.

Method Detail

clone

org.eclipse.jgit.api.Git clone(DirectoryResource dir,
                             String repoUri)
                               throws org.eclipse.jgit.api.errors.GitAPIException

Clones a GIT repository.

Parameters:

dir - The target location where the GIT repository will be cloned. It should not exist, or if exists, it should be an empty directory.

repoUri - The URI pointing to the source of the repository which will be cloned.

Returns:

A JGit API handle to the GIT object pointing to the cloned repository.

Throws:

org.eclipse.jgit.api.errors.GitAPIException - Thrown when there are problems cloning the repository.

git

org.eclipse.jgit.api.Git git(DirectoryResource dir)
                             throws IOException

Returns a handle to an existing Git repository.

Parameters:

dir - The directory containing the GIT repository

Returns:

A JGit API handle to the specified directory.

Throws:

IOException - Thrown when there are problems accessing the specified directory.

checkout

org.eclipse.jgit.lib.Ref checkout(org.eclipse.jgit.api.Git git,
                                String remote,
                                boolean createBranch,
                                org.eclipse.jgit.api.CreateBranchCommand.SetupUpstreamMode mode,
                                boolean force)
                                  throws org.eclipse.jgit.api.errors.GitAPIException

Checks out or creates a given GIT branch.

Parameters:

git - A JGit API handle to the directory, where branches will be checked out.

remote - The name of the branch that will be created/checked out.

createBranch - If true, the specified branch will be created

mode - When creating a branch, specifies whether it should track its remote branch as upstream.

force - If true, forces resetting the starting point of the newly switched branch.

Returns:

A Ref object (part of the JGit API), pointing to the checked out branch.

Throws:

org.eclipse.jgit.api.errors.GitAPIException - Thrown when there are problems checking out the new branch.

checkout

org.eclipse.jgit.lib.Ref checkout(org.eclipse.jgit.api.Git git,
                                org.eclipse.jgit.lib.Ref localRef,
                                org.eclipse.jgit.api.CreateBranchCommand.SetupUpstreamMode mode,
                                boolean force)
                                  throws org.eclipse.jgit.api.errors.GitAPIException

Checks out an already existing branch.

Parameters:

git - A JGit API handle to the directory, where branches will be checked out.

localRef - A GIT object pointing to the branch to be checked out.

mode - When creating a branch, specifies whether it should track its remote branch as upstream.

force - If true, forces resetting the starting point of the newly switched branch.

Returns:

A Ref object (part of the JGit API), pointing to the checked out branch.

Throws:

org.eclipse.jgit.api.errors.GitAPIException - Thrown when there are problems checking out the new branch.

fetch

org.eclipse.jgit.transport.FetchResult fetch(org.eclipse.jgit.api.Git git,
                                           String remote,
                                           String refSpec,
                                           int timeout,
                                           boolean fsck,
                                           boolean dryRun,
                                           boolean thin,
                                           boolean prune)
                                             throws org.eclipse.jgit.api.errors.GitAPIException

Fetches the Git objects from a remote repository.

Parameters:

git - A JGit API handle to the repository, where the refs will be fetched to.

remote - A URI or name of a remote branch, where the refs will be fetched from.

refSpec - A space-separated list of ref specs. May be null.

timeout - If greater than 0, a timeout for the fetch operation.

fsck - If set to true, objects that will be fetched will be checked for validity.

dryRun - If set to true, this fetch is marked as a dry run.

thin - Sets the thin-pack reference for this fetch operation.

prune - If set to true the objects that do not exist anymore, will be removed in the source.

Returns:

A FetchResult object (part of the JGit API), specifying the status of this fetch operation.

Throws:

org.eclipse.jgit.api.errors.GitAPIException - Thrown when there are problems fetching the refs

init

org.eclipse.jgit.api.Git init(DirectoryResource dir)
                              throws IOException

Initializes a new GIT repository.

Parameters:

dir - The directory in which to create a new .git/ folder and repository.

Returns:

A JGit API handle to the specified directory.

Throws:

IOException - Thrown when there are problems accessing the specified directory.

pull

org.eclipse.jgit.api.PullResult pull(org.eclipse.jgit.api.Git git,
                                   int timeout)
                                     throws org.eclipse.jgit.api.errors.GitAPIException

Pulls the latest changes from the remote repository and incorporates them into the given one.

Parameters:

git - A JGit API handle to the repository, where the changes will be pulled to.

timeout - If greater than 0, the timeout, used for the fetching step

Returns:

A PullResult object (part of the JGit API), that specifies the result of the pull action.

Throws:

org.eclipse.jgit.api.errors.GitAPIException - Thrown when there are problems pulling the latest changing

getRemoteBranches

List<org.eclipse.jgit.lib.Ref> getRemoteBranches(org.eclipse.jgit.api.Git repo)
                                                 throws org.eclipse.jgit.api.errors.GitAPIException

Returns all the remote branches of a given GIT repository.

Parameters:

repo - A JGit API handle to the repository, which remote branches will be listed.

Returns:

A list of Ref objects (part of the JGit API), that identify the remote branches for the given repository.

Throws:

org.eclipse.jgit.api.errors.GitAPIException - Thrown when there are problems obtaining the list of remote branches.

getLocalBranches

List<org.eclipse.jgit.lib.Ref> getLocalBranches(org.eclipse.jgit.api.Git repo)
                                                throws org.eclipse.jgit.api.errors.GitAPIException

Returns all the local branches of a given GIT repository.

Parameters:

repo - A JGit API handle to the repository, which local branches will be listed.

Returns:

A list of Ref objects (part of the JGit API), that identify the local branches for the given repository.

Throws:

org.eclipse.jgit.api.errors.GitAPIException - Thrown when there are problems obtaining the list of local branches.

getCurrentBranchName

String getCurrentBranchName(org.eclipse.jgit.api.Git repo)
                            throws IOException

Returns the name of the branch that is currently checked out in the given repository.

Parameters:

repo - A JGit API handle to the repository.

Returns:

The name of the currently checked out branch in the given repository.

Throws:

IOException - If there are problems accessing the directory of the GIT repository.

switchBranch

org.eclipse.jgit.lib.Ref switchBranch(org.eclipse.jgit.api.Git repo,
                                    String branchName)

Changes the currently checked out branch of a given repository.

Parameters:

repo - A JGit API handle to the repository, where the new branch will be checked out.

branchName - The name of the branch which will be checked out.

Returns:

A Ref object (part of the JGit API), pointing to the checked out branch.

getLogForCurrentBranch

List<String> getLogForCurrentBranch(org.eclipse.jgit.api.Git repo)
                                    throws org.eclipse.jgit.api.errors.GitAPIException

Returns a list of the messages of all the commits in the current branch.

Parameters:

repo - A JGit API handle to the repository, which commit messages will be listed.

Returns:

A list of all the commit messages for the current branch

Throws:

org.eclipse.jgit.api.errors.GitAPIException - Thrown when there are problems obtaining the list of the commit messages.

getLogForBranch

List<String> getLogForBranch(org.eclipse.jgit.api.Git repo,
                           String branchName)
                             throws org.eclipse.jgit.api.errors.GitAPIException,
                                    IOException

Returns a list of the messages of all the commits for a given branch.

Parameters:

repo - A JGit API handle to the repository, which commit messages will be listed.

branchName - The branch which log messages will be returned.

Returns:

A list of all the commit messages for the given branch.

Throws:

org.eclipse.jgit.api.errors.GitAPIException - Thrown when there are problems obtaining the list of the commit messages.

IOException

add

void add(org.eclipse.jgit.api.Git repo,
       String filePattern)
         throws org.eclipse.jgit.api.errors.GitAPIException

Stages the files matching the given pattern from the working tree to the GIT index.

Parameters:

repo - The JGit API handle to the repository, where files will be added.

filePattern - The file to be added to the index. If a directory is passed, its content will be added recursively.

Throws:

org.eclipse.jgit.api.errors.GitAPIException - Thrown when there are problems adding files to the GIT index.

addAll

void addAll(org.eclipse.jgit.api.Git repo)
            throws org.eclipse.jgit.api.errors.GitAPIException

Stages all the new, modified and deleted files from the working tree to the GIT index.

Parameters:

repo - The JGit API handle to the repository, where files will be added.

Throws:

org.eclipse.jgit.api.errors.GitAPIException - Thrown when there are problems adding files to the GIT index.

commit

void commit(org.eclipse.jgit.api.Git repo,
          String message)
            throws org.eclipse.jgit.api.errors.GitAPIException

Creates a new commit with the current contents of the index along with a log message.

Parameters:

repo - The JGit API handle to the repository, where the commit will be created.

message - The commit message.

Throws:

org.eclipse.jgit.api.errors.GitAPIException - Thrown when there are problems creating the commit.

commitAll

void commitAll(org.eclipse.jgit.api.Git repo,
             String message)
               throws org.eclipse.jgit.api.errors.GitAPIException

Stages all the new, modified and deleted files to the index and creates a commit from its current contents.

Parameters:

repo - The JGit API handle to the repository, where the commit will be created.

message - The commit message.

Throws:

org.eclipse.jgit.api.errors.GitAPIException - Thrown when there are problems creating the commit.

stashCreate

void stashCreate(org.eclipse.jgit.api.Git repo)
                 throws org.eclipse.jgit.api.errors.GitAPIException

Stashes the contents on the working directory and index in separate commits and resets to the current HEAD commit.

Parameters:

repo - The JGit API handle to the repository, where the stash action will be performed.

Throws:

org.eclipse.jgit.api.errors.GitAPIException - Thrown when there are problems performing the stash action.

stashApply

void stashApply(org.eclipse.jgit.api.Git repo,
              String... stashRef)
                throws org.eclipse.jgit.api.errors.GitAPIException

Applies the changes in a stashed commit to the working directory and index.

Parameters:

repo - The JGit API handle to the repository, where the stash action will be performed.

stashRef - The stash reference to apply.

Throws:

org.eclipse.jgit.api.errors.GitAPIException - Thrown when there are problems performing the stash action.

stashDrop

void stashDrop(org.eclipse.jgit.api.Git repo)
               throws org.eclipse.jgit.api.errors.GitAPIException

Drops the last stashed commit.

Parameters:

repo - The JGit API handle to the repository, where the stash action will be performed.

Throws:

org.eclipse.jgit.api.errors.GitAPIException - Thrown when there are problems performing the stash action.

cherryPick

void cherryPick(org.eclipse.jgit.api.Git repo,
              org.eclipse.jgit.lib.Ref commit)
                throws org.eclipse.jgit.api.errors.GitAPIException

Cherry-picks a given commit to the current HEAD.

Parameters:

repo - The JGit API handle to the repository, where the cherry-pick action will be performed.

commit - A reference to the commit, which will be cherry-picked to the current HEAD.

Throws:

org.eclipse.jgit.api.errors.GitAPIException - Thrown when there are problems performing the cherry-pick action.

cherryPickNoMerge

org.eclipse.jgit.api.CherryPickResult cherryPickNoMerge(org.eclipse.jgit.api.Git git,
                                                      org.eclipse.jgit.lib.Ref commit)
                                                        throws org.eclipse.jgit.api.errors.GitAPIException,
                                                               CantMergeCommitException

Does the same as the original cherry-pick except committing after running merger.

Parameters:

repo - The JGit API handle to the repository, where the cherry-pick action will be performed.

commit - A reference to the commit, which will be cherry-picked to the current HEAD.

Returns:

A CherryPickResult object (part of the JGit API), encapsulating the result of the cherry-pick command.

Throws:

org.eclipse.jgit.api.errors.GitAPIException - Thrown when there are problems performing the cherry-pick action.

CantMergeCommitException - Thrown when the commit to cherry-pick has no parents.

resetHard

void resetHard(org.eclipse.jgit.api.Git repo,
             String newBase)
               throws org.eclipse.jgit.api.errors.GitAPIException

Resets the HEAD, the index and the working tree to point to the given commit.

Parameters:

repo - The JGit API handle to the repository, which will be reset.

newBase - The commit to which the HEAD will be reset.

Throws:

org.eclipse.jgit.api.errors.GitAPIException - Thrown when there are problems performing the reset action.

createBranch

org.eclipse.jgit.lib.Ref createBranch(org.eclipse.jgit.api.Git git,
                                    String branchName)
                                      throws org.eclipse.jgit.api.errors.GitAPIException

Creates a new branch in the given GIT repository and checks it out.

Parameters:

repo - The JGit API handle to the repository, where a new branch will be created.

branchName - The name of the branch that will be created.

Returns:

A Ref object (part of the JGit API), pointing to the created branch.

Throws:

org.eclipse.jgit.api.errors.GitAPIException - Thrown when there are problems creating the new branch.

close

void close(org.eclipse.jgit.api.Git repo)

Closes the resources and decrements the use count of the given repository.

Parameters:

repo - The repository where the close action will be performed.