README.asciidoc

git-tools

This addon provides both standalone functionality to be used in other addons as well as commands.

The git-tools addon enables creating and cloning GIT repositories, working with branches, commits and other Git objects.

It has some useful commands for setting up .gitIgnore files.

Depends on

Addon	Exported	Optional
ui	no	no
configuration	no	no
resource	no	no
projects	no	no
facets	no	no
org.jboss.forge.furnace.container:cdi	no	no

Setup

This Addon requires the following installation steps.

Add git-tools to pom.xml

To use this addon, you must add it as a dependency in the pom.xml of your forge-addon classified artifact:

<dependency>
   <groupId>org.jboss.forge.addon</groupId>
   <artifactId>git-tools</artifactId>
   <classifier>forge-addon</classifier>
   <version>${version}</version>
</dependency>

Features

Obtaining GIT utilities

Allows for programatically manipulating GIT repositories. Works as a wrapper over the JGit library.

@Inject
private GitUtils gitUtils;

Tip	If your addon uses a container that does not support "@Inject" annotations, services such as the GitUtils may also be accessed via the AddonRegistry: + Imported<GitUtils> imported = addonRegistry.getServices(GitUtils.class); GitUtils gitUtils = imported.get(); +

Cloning a GIT repository

Once you have access to the GitUtils object, you can use it to clone an existing GIT repository. Most of the other git utilities work with the Git object returned from this operation, so it is a good idea to cache it.

import org.eclipse.jgit.api.Git;

// ...

private Git gitHandle;

private void cloneRepository(String remoteUri, DirectoryResource localDirectory)
{
   this.gitHandle = gitUtils.clone(localDirectory, remoteUri);
}

You can obtain the gitHandle object of an existing local repository by simply calling the `git` method of gitUtils:

private Git getGitRepository(DirectoryResource localDirectory)
{
   return gitUtils.git(localDirectory);
}

Working with branches

The GIT utilities provide handy methods for listing, checking out and creating branches. For all of them you will need the gitHandle object, obtained when cloning or getting a GIT repository.

// List all the local branches
List<Ref> localBranches = gitUtils.getLocalBranches(gitHandle);

// Create a branch
gitUtils.createBranch(gitHandle, "FORGE-123");

// Get current branch name
String currentBranch = gitUtils.getCurrentBranchName(gitHandle);

// Checkout 'master' branch
gitUtils.checkout(gitHandle, "master", false, null, false);

Staging files to index

You can use the GIT utilities to perform adding new, modified and deleted files from the GIT working tree to the staging area.

// Stage files with a certain pattern
gitUtils.add(gitHandle, "src\");

// Stage all the files in the working tree
gitUtils.addAll(gitHandle);

Working with commits

GIT utilities allow for creating, stashing and cherry picking commits. There is also functionality for reseting the HEAD to a previous state. At the moment there is only hard reset, i.e. reset the HEAD, the index and the working tree.

// Commit the staged files along with a message
gitUtils.commit(gitHandle, "This is a test commit message");

// Stage all the files in the working tree and then commit them along with a message
gitUtils.commitAll(gitHandle, "This is a test commit message");

// Stash the content of the working tree and the index into separate commits
gitUtils.stashCreate(gitHandle);

// Reset to the previous commit
gitUtils.resetHard(gitHandle, "f414f31");

UI commands

The git-tools addon provides a few handy UI commands for working with GIT repositories as well as for setting up and manipulating the .gitignore file

Working with GIT repositories

You can init a GIT repository in an existing project by running the git-setup command. You may use the git-clone command to clone a remote repository to a local directory. The git-checkout command may be used for creating or checking out existing branches.

Working with .gitignore

There are some UI commands for working with .gitignore. You can set everything up by running gitignore-setup inside an existing project. It will download from a remote repository a list of .gitignore template files for almost all the programs that create artefacts that should be ignored by GIT. The git-create command will create the .gitignore file in the root of the current project and will add there all the patterns from a list of templates, provided by the user. There are commands for adding, deleting and listing the patterns in the .gitignore file.