Overview (Git Client Library)

Git Client Library
Package	Description
org.netbeans.libs.git
org.netbeans.libs.git.progress

The library is a facade over a java implementation of Git client - JGit. Because JGit does not provide a full-featured high-level API (on the level of whole git commands), this library groups the JGit low-level API into bigger pieces and exports the API in the form of full Git commandline commands (e.g. status, commit, checkout, reset, etc.). GitlibraryAPI Allows clients to work with local Git repositories and invoke a set of Git commands affecting a Git repository.

What is New (see all changes)?

Mar 12 '13 Adding support comparing trees of arbitrary commits
- Adding a new method GitClient.getStatus(File[], String, ProgressMonitor) allowing an API client to get statuses of local files not just against the HEAD but against an arbitrary commit.
- Adding a new method GitClient.getStatus(File[], String, String, ProgressMonitor) allowing an API client to get modifications from the Git history. It is similar to GitRevisionInfo.getModifications but returns file statuses between two arbitrary commits and not just a commit and its parent.
Mar 11 '13 Adding support for rebase to the API
- Adding a new method GitClient.rebase delegating to the rebase command.
Feb 6 '13 Adding new method to GitClient: commit(), amending the last commit
Git supports commit amendments, in other words modifying the last commit and changing its commit message or modified files. Another commit method allows API clients to specify either to amend the last commit or to make a fresh new commit on top of current HEAD.
Nov 16 '12 Adding new method to GitClient: release()
JGit repository normally does not close all opened file descriptors and prevents external commands from working with the same repository. Clients of the JGit API are supposed to call JGitRepository.close() when they're done with the repository. We need to pass this method to the Git Library API so when clients are done with calling all required commands the library closes all descriptors and frees the git metadata files for other tools.
Mar 11 '12 Initial version of the API

Use Cases

Get Git client

Before you can run preferred Git commands, you must get an instance of GitClient bound to a specific repository.
Instances of GitClient are provided by GitRepository. GitRepository represents a concrete local Git repository and is always bound to a specific folder.

The correct way to achieve this is to call GitRepository.getInstance(repositoryRoot).createClient().

Run Git commands

To run a Git command simply call a method mapped to the command on an instance of GitClient.

Control Git command's workflow

You are able to control a Git command's work and listen for warning and error messages and informative messages indicating start and finish of the command via ProgressMonitor. Every method of GitClient mapped to a Git command accepts an instance of ProgressMonitor as a parameter. Through an instance of this class you can cancel a command, an implementation of such a command periodically calls isCanceled and interrupts its work if the method returns true.
Its basic implementation at ProgressMonitor.DefaultProgressMonitor supports canceling commands while implementing other methods as no-op.

Recieve notifications

Some Git commands may take a noticeable amount of time to finish and waiting that long for the full result returned by the command may not be sufficient. Git API provides a way to follow the process of building the result of such commands.
Let's say you want to get all revisions from the Git history. The log command is expensive especially on large repositories and you do not want to wait for it to finish but want to be notified when a single revision from the history is fetched and added to the result. This way you can incrementally present the result in the UI without the need for waiting indefinitely for the command to finish.

Package org.netbeans.libs.git.progress offers a set of listeners extending the NotificationListener interface which you can attach to an instance of GitClient via addNotificationListener() and through which you can closely monitor building of the result.

Exported Interfaces

This table lists all of the module exported APIs with defined stability classifications. It is generated based on answers to questions about the architecture of the module. Read them all...

Group of java interfaces

Interface Name	In/Out	Stability	Specified in What Document?
GitlibraryAPI	Exported	Under Development	Allows clients to work with local Git repositories and invoke a set of Git commands affecting a Git repository.

Group of property interfaces

Interface Name

In/Out

Stability

Specified in What Document?

Implementation Details

Where are the sources for the module?

The sources for the module are in the NetBeans Mercurial repositories.

What do other modules need to do to declare a dependency on this one, in addition to or instead of a plain module dependency?

No additional setting is needed, direct dependency is enough.

Read more about the implementation in the answers to architecture questions.

Git Client LibraryUnder Development