Instances of a git client are provided by {@link GitRepository}. To get one call * {@link GitRepository#createClient() }.
*Some git client commands may (or may not) require additional setup of the client to successfully finish their work.
* One quite usual use case is setting an instance of {@link GitClientCallback} to the client so commands like push,
* fetch or pull may connect to and access a remote repository. To set an instance of GitClientCallback
* use {@link #setCallback(org.netbeans.libs.git.GitClientCallback) } method.
Certain git commands may take a long time to finish and they are capable of notifying the world about the progress in their work.
* If you want to be notified about such changes while the command is in process, attach a listener to the client
* via {@link #addNotificationListener(org.netbeans.libs.git.progress.NotificationListener) }.
* An example can be the log command. Digging through the history may take a lot of time so if you do not want to wait for the complete result only
* and want to present the commit information incrementally as it is accepted one by one into the result, you can do so by adding an instance of
* {@link RevisionInfoListener} to the client.
When you have the client correctly set up, you may call any git command we support. The commands are mapped to appropriate methods in GitClient.
*
Every method representing a git command accepts as a parameter an instance of {@link ProgressMonitor}. With that class you may affect the flow of commands - it
* has the ability to cancel running git commands - and listen for error or information messages the commands produce.
null for blaming a checked-out file against HEAD
* @param monitor progress monitor
* @return annotation information
* @throws org.netbeans.libs.git.GitException.MissingObjectException when the revision revision cannot be resolved.
* @throws GitException an unexpected error occurs
*/
public GitBlameResult blame (File file, String revision, ProgressMonitor monitor) throws GitException.MissingObjectException, GitException {
Repository repository = gitRepository.getRepository();
BlameCommand cmd = new BlameCommand(repository, getClassFactory(), file, revision, monitor);
cmd.execute();
return cmd.getResult();
}
/**
* Prints file's content in the given revision to output stream
* @param file file to cat
* @param revision git revision, never null
* @param out output stream to print the content to.
* @return true if the file was found in the specified revision and printed to out, otherwise false
* @throws GitException.MissingObjectException if the given revision does not exist
* @throws GitException an unexpected error occurs
*/
public boolean catFile (File file, String revision, java.io.OutputStream out, ProgressMonitor monitor) throws GitException.MissingObjectException, GitException {
Repository repository = gitRepository.getRepository();
CatCommand cmd = new CatCommand(repository, getClassFactory(), file, revision, out, monitor);
cmd.execute();
return cmd.foundInRevision();
}
/**
* Prints content of an index entry accordant to the given file to the given output stream
* @param file file whose relevant index entry to cat
* @param stage version of the file in the index. In case of a merge conflict there are usually more
* versions of the file. 0 for normal non-conflict version,
* 1 for the base version,
* 2 for the first merged version ("ours") and
* 3 for the second merged version ("theirs").
* @param out output stream
* @return true if the file was found in the index and printed to out, otherwise false
* @throws GitException an unexpected error occurs
*/
public boolean catIndexEntry (File file, int stage, java.io.OutputStream out, ProgressMonitor monitor) throws GitException {
Repository repository = gitRepository.getRepository();
CatCommand cmd = new CatCommand(repository, getClassFactory(), file, stage, out, monitor);
cmd.execute();
return cmd.foundInRevision();
}
/**
* Checks out the index into the working copy root. Does not move current HEAD.
* @param revision if not null, index is updated with the revision content before checking out to WC
* @param roots files/folders to checkout
* @param recursively if set to true, all files under given roots will be checked out, otherwise only roots and direct file children will be affected.
* @throws GitException an unexpected error occurs
*/
public void checkout(File[] roots, String revision, boolean recursively, ProgressMonitor monitor) throws GitException.MissingObjectException, GitException {
Repository repository = gitRepository.getRepository();
if (revision != null) {
ResetCommand cmd = new ResetCommand(repository, getClassFactory(), revision, roots, recursively, monitor, delegateListener);
cmd.execute();
}
if (!monitor.isCanceled()) {
CheckoutIndexCommand cmd = new CheckoutIndexCommand(repository, getClassFactory(), roots, recursively, monitor, delegateListener);
cmd.execute();
}
}
/**
* Checks out a given revision, modifies the Index as well as the Working tree.
* @param revision cannot be null. If the value equals to anything other than an existing branch name, the revision will be checked out
* and the working tree will be in the detached HEAD state.
* @param failOnConflict if set to false, the command tries to merge local changes into the new branch
* @throws GitException an unexpected error occurs
*/
public void checkoutRevision (String revision, boolean failOnConflict, ProgressMonitor monitor) throws GitException.MissingObjectException, GitException {
if (!failOnConflict) {
throw new IllegalArgumentException("Currently unsupported. failOnConflict must be set to true. JGit lib is buggy."); //NOI18N
}
Repository repository = gitRepository.getRepository();
CheckoutRevisionCommand cmd = new CheckoutRevisionCommand(repository, getClassFactory(), revision, failOnConflict, monitor, delegateListener);
cmd.execute();
}
/**
* Cleans the working tree by recursively removing files that are not under
* version control starting from the given roots.
* @param roots files or folders to recursively remove from disk, versioned files under these files will not be deleted.
* @param monitor progress monitor
* @throws GitException an unexpected error occurs
*/
public void clean(File[] roots, ProgressMonitor monitor) throws GitException {
Repository repository = gitRepository.getRepository();
CleanCommand cmd = new CleanCommand(repository, getClassFactory(), roots, monitor, delegateListener);
cmd.execute();
}
/**
* Commits all changes made in the index to all files under the given roots
* @param roots files or folders to recursively commit.
* @param commitMessage commit message
* @param author person who is the author of the changes to be committed
* @param commiter person who is committing the changes, may not be the same person as author.
* @param monitor progress monitor
* @throws GitException an unexpected error occurs
*/
public GitRevisionInfo commit(File[] roots, String commitMessage, GitUser author, GitUser commiter, ProgressMonitor monitor) throws GitException {
return commit(roots, commitMessage, author, commiter, false, monitor);
}
/**
* Commits all changes made in the index to all files under the given roots
* @param roots files or folders to recursively commit.
* @param commitMessage commit message
* @param author person who is the author of the changes to be committed
* @param commiter person who is committing the changes, may not be the same person as author.
* @param amend amends and modifies the last commit instead of adding a completely new commit
* @param monitor progress monitor
* @throws GitException an unexpected error occurs
*/
public GitRevisionInfo commit(File[] roots, String commitMessage, GitUser author, GitUser commiter, boolean amend, ProgressMonitor monitor) throws GitException {
Repository repository = gitRepository.getRepository();
CommitCommand cmd = new CommitCommand(repository, getClassFactory(), roots, commitMessage, author, commiter, amend, monitor);
cmd.execute();
return cmd.revision;
}
/**
* The index entries representing files under the source are copied and the newly created entries represent the corresponding files under the target.
* Modifies only the index.
* @param source source tree to copy
* @param target target file or folder the source should be copied onto.
* @param monitor progress monitor
* @throws GitException an unexpected error occurs
*/
public void copyAfter (File source, File target, ProgressMonitor monitor) throws GitException {
Repository repository = gitRepository.getRepository();
CopyCommand cmd = new CopyCommand(repository, getClassFactory(), source, target, monitor, delegateListener);
cmd.execute();
}
/**
* Creates a new branch with a given name, starting at the given revision
* @param branchName name that should be assigned to the new branch
* @param revision revision that should be referenced by the new branch
* @param monitor progress monitor
* @return created branch
* @throws GitException an unexpected error occurs
*/
public GitBranch createBranch (String branchName, String revision, ProgressMonitor monitor) throws GitException {
CreateBranchCommand cmd = new CreateBranchCommand(gitRepository.getRepository(), getClassFactory(), branchName, revision, monitor);
cmd.execute();
return cmd.getBranch();
}
/**
* Creates a tag for any object represented by a given taggedObjectId.
* If message is set to null or an empty value and signed set to false than this method creates a lightweight tag.
* @param tagName name of the new tag
* @param taggedObject object to tag
* @param message tag message
* @param signed if the tag should be signed. Currently unsupported.
* @param forceUpdate if a tag with the same name already exists, the method fails and throws an exception unless this is set to true. In that case the
* old tag is replaced with the new one.
* @param monitor progress monitor
* @return the created tag
* @throws GitException an unexpected error occurs
*/
public GitTag createTag (String tagName, String taggedObject, String message, boolean signed, boolean forceUpdate, ProgressMonitor monitor) throws GitException {
CreateTagCommand cmd = new CreateTagCommand(gitRepository.getRepository(), getClassFactory(), tagName, taggedObject, message, signed, forceUpdate, monitor);
cmd.execute();
return cmd.getTag();
}
/**
* Deletes a given branch from the repository
* @param branchName name of a branch to delete.
* @param forceDeleteUnmerged if set to true then trying to delete an unmerged branch will not fail but will forcibly delete the branch
* @param monitor progress monitor
* @throws GitException.NotMergedException branch has not been fully merged yet and forceDeleteUnmerged is set to false
* @throws GitException an unexpected error occurs
*/
public void deleteBranch (String branchName, boolean forceDeleteUnmerged, ProgressMonitor monitor) throws GitException.NotMergedException, GitException {
DeleteBranchCommand cmd = new DeleteBranchCommand(gitRepository.getRepository(), getClassFactory(), branchName, forceDeleteUnmerged, monitor);
cmd.execute();
}
/**
* Deletes a given tag from the repository
* @param tagName name of a tag to delete
* @param monitor progress monitor
* @throws GitException an unexpected error occurs
*/
public void deleteTag (String tagName, ProgressMonitor monitor) throws GitException {
DeleteTagCommand cmd = new DeleteTagCommand(gitRepository.getRepository(), getClassFactory(), tagName, monitor);
cmd.execute();
}
/**
* Exports a given commit in the format accepted by git am
* @param commit id of a commit whose diff to export
* @param out output stream the diff will be printed to
* @param monitor progress monitor
* @throws GitException an unexpected error occurs
*/
public void exportCommit (String commit, OutputStream out, ProgressMonitor monitor) throws GitException {
ExportCommitCommand cmd = new ExportCommitCommand(gitRepository.getRepository(), getClassFactory(), commit, out, monitor, delegateListener);
cmd.execute();
}
/**
* Exports uncommitted changes in files under given roots to the given output stream
* @param roots the diff will be exported only for modified files under these roots, can be empty to export all modifications in the whole working tree
* @param mode defines the compared trees
* @param out output stream the diff will be printed to
* @param monitor progress monitor
* @throws GitException an unexpected error occurs
*/
public void exportDiff (File[] roots, DiffMode mode, OutputStream out, ProgressMonitor monitor) throws GitException {
ExportDiffCommand cmd = new ExportDiffCommand(gitRepository.getRepository(), getClassFactory(), roots, mode, out, monitor, delegateListener);
cmd.execute();
}
/**
* Fetches remote changes for references specified in the config file under a given remote.
* @param remote should be a name of a remote set up in the repository config file
* @param monitor progress monitor
* @return result of the command with listed local reference updates
* @throws GitException.AuthorizationException when the authentication or authorization fails
* @throws GitException an unexpected error occurs
*/
public Mapfalse then only local (and no remote) branches will be returned
* @return all known branches in the repository
* @throws GitException an unexpected error occurs
*/
public Mapfalse, only commit tags, otherwise tags for all objects are returned
* @return all known tags from the repository
* @throws GitException an unexpected error occurs
*/
public Mapnull if none found.
* @param revisions revisions whose common ancestor to search
* @param monitor progress monitor
* @return common ancestor for given revisions or null if none found.
* @throws GitException an unexpected error occurs
*/
public GitRevisionInfo getCommonAncestor (String[] revisions, ProgressMonitor monitor) throws GitException {
GetCommonAncestorCommand cmd = new GetCommonAncestorCommand(gitRepository.getRepository(), getClassFactory(), revisions, monitor);
cmd.execute();
return cmd.getRevision();
}
/**
* Returns an ancestor revision that affected a given file
* @param file limit the result only on revision that actually modified somehow the file
* @param revision revision to start search from, only its ancestors will be investigated
* @param monitor progress monitor
* @return an ancestor of a given revision that affected the given file or null if none found.
* @throws GitException an unexpected error occurs
*/
public GitRevisionInfo getPreviousRevision (File file, String revision, ProgressMonitor monitor) throws GitException {
GetPreviousCommitCommand cmd = new GetPreviousCommitCommand(gitRepository.getRepository(), getClassFactory(), file, revision, monitor);
cmd.execute();
return cmd.getRevision();
}
/**
* Similar to {@link #getStatus(java.io.File[], org.netbeans.libs.git.progress.ProgressMonitor)}, but returns only conflicts.
* @param roots files to search the conflicts under
* @param monitor progress monitor
* @return conflicted files and their accordant statuses
* @throws GitException an unexpected error occurs
*/
public Mapnull if no remote with such name was found
* @throws GitException an unexpected error occurs
*/
public GitRemoteConfig getRemote (String remoteName, ProgressMonitor monitor) throws GitException {
return getRemotes(monitor).get(remoteName);
}
/**
* Returns all remote configurations set up for this repository
* @param monitor progress monitor
* @return all known remote configurations
* @throws GitException an unexpected error occurs
*/
public MapworkDir or cannot be created for other reasons.
*/
public void init (ProgressMonitor monitor) throws GitException {
Repository repository = gitRepository.getRepository();
InitRepositoryCommand cmd = new InitRepositoryCommand(repository, getClassFactory(), monitor);
cmd.execute();
}
/**
* Returns files that are marked as modified between the HEAD and Index.
* @param roots files or folders to search for modified files.
* @param monitor progress monitor
* @throws GitException an unexpected error occurs
*/
public File[] listModifiedIndexEntries (File[] roots, ProgressMonitor monitor) throws GitException {
Repository repository = gitRepository.getRepository();
ListModifiedIndexEntriesCommand cmd = new ListModifiedIndexEntriesCommand(repository, getClassFactory(), roots, monitor, delegateListener);
cmd.execute();
return cmd.getFiles();
}
/**
* Returns available branches in a given remote repository
* @param remoteRepositoryUrl url of the remote repository
* @param monitor progress monitor
* @return collection of available branches in the remote repository
* @throws GitException.AuthorizationException when the authentication or authorization fails
* @throws GitException an unexpected error occurs
*/
public Maptrue then this will fail if a merge commit is needed and
* cannot simply update reference pointers
* @param monitor progress monitor
* @return result of the command containing the list of updated local references
* @throws GitException.AuthorizationException when the authentication or authorization fails
* @throws GitException.CheckoutConflictException there are local changes in the working tree that would result in a merge conflict
* @throws GitException.MissingObjectException given branch to merge does not exist
* @throws GitException an unexpected error occurs
* @since 1.8
*/
public GitPullResult pull (String remote, Listtrue the working tree will not be affected
* @param monitor progress monitor
* @throws GitException an unexpected error occurs
*/
public void remove (File[] roots, boolean cached, ProgressMonitor monitor) throws GitException {
Repository repository = gitRepository.getRepository();
RemoveCommand cmd = new RemoveCommand(repository, getClassFactory(), roots, cached, monitor, delegateListener);
cmd.execute();
}
/**
* Removes an already added notification listener. Such a listener will not get notifications from the
* git subsystem.
* @param listener listener to remove.
*/
public void removeNotificationListener (NotificationListener listener) {
synchronized (listeners) {
listeners.remove(listener);
}
}
/**
* Removes remote configuration from the repository's config file
* @param remote name of the remote
* @param monitor progress monitor
* @throws GitException an unexpected error occurs
*/
public void removeRemote (String remote, ProgressMonitor monitor) throws GitException {
Repository repository = gitRepository.getRepository();
RemoveRemoteCommand cmd = new RemoveRemoteCommand(repository, getClassFactory(), remote, monitor);
cmd.execute();
}
/**
* Renames source file or folder to target
* @param source file or folder to be renamed
* @param target target file or folder. Must not yet exist.
* @param after set to true if you don't only want to correct the index
* @param monitor progress monitor
* @throws GitException an unexpected error occurs
*/
public void rename (File source, File target, boolean after, ProgressMonitor monitor) throws GitException {
Repository repository = gitRepository.getRepository();
RenameCommand cmd = new RenameCommand(repository, getClassFactory(), source, target, after, monitor, delegateListener);
cmd.execute();
}
/**
* Updates entries for given files in the index with those from the given revision
* @param revision revision to go back to
* @param roots files or folders to update in the index
* @param recursively if set to true, all files under given roots will be affected, otherwise only roots and direct file children will be modified in the index.
* @param monitor progress monitor
* @throws GitException.MissingObjectException if the given revision does not exist
* @throws GitException an unexpected error occurs
*/
public void reset (File[] roots, String revision, boolean recursively, ProgressMonitor monitor) throws GitException.MissingObjectException, GitException {
Repository repository = gitRepository.getRepository();
ResetCommand cmd = new ResetCommand(repository, getClassFactory(), revision, roots, recursively, monitor, delegateListener);
cmd.execute();
}
/**
* Sets HEAD to the given revision and updates index and working copy accordingly to the given reset type
* @param revision revision HEAD will reference to
* @param resetType type of reset, see git help reset
* @param monitor progress monitor
* @throws GitException.MissingObjectException if the given revision does not exist
* @throws GitException an unexpected error occurs
*/
public void reset (String revision, ResetType resetType, ProgressMonitor monitor) throws GitException.MissingObjectException, GitException {
Repository repository = gitRepository.getRepository();
ResetCommand cmd = new ResetCommand(repository, getClassFactory(), revision, resetType, monitor, delegateListener);
cmd.execute();
}
/**
* Reverts already committed changes and creates an inverse commit.
* @param revision the id of a commit to revert
* @param commitMessage used as the commit message for the revert commit. If set to null or an empty value, a default value will be used for the commit message
* @param commit if set to false, the revert modifications will not be committed but will stay in index
* @param monitor progress monitor
* @return result of the revert command
* @throws GitException.MissingObjectException if the given revision does not exist
* @throws GitException.CheckoutConflictException there are local modifications in Working Tree, merge fails in such a case
* @throws GitException an unexpected error occurs
*/
public GitRevertResult revert (String revision, String commitMessage, boolean commit, ProgressMonitor monitor)
throws GitException.MissingObjectException, GitException.CheckoutConflictException, GitException {
Repository repository = gitRepository.getRepository();
RevertCommand cmd = new RevertCommand(repository, getClassFactory(), revision, commitMessage, commit, monitor);
cmd.execute();
return cmd.getResult();
}
/**
* Sets credentials callback for this client.
* Some actions (like inter-repository commands) may need it for its work to communicate with an external repository.
* @param callback callback implementation providing credentials for an authentication process.
*/
public void setCallback (GitClientCallback callback) {
this.credentialsProvider = callback == null ? null : new JGitCredentialsProvider(callback);
}
/**
* Sets the remote configuration in the configuration file.
* @param remoteConfig new remote config to store as a remote section in the repository's config file.
* @param monitor progress monitor
*/
public void setRemote (GitRemoteConfig remoteConfig, ProgressMonitor monitor) throws GitException {
Repository repository = gitRepository.getRepository();
SetRemoteCommand cmd = new SetRemoteCommand(repository, getClassFactory(), remoteConfig, monitor);
cmd.execute();
}
/**
* Unignores given files
* @param files files to mark unignored again and remove their respective record from gitignore files.
* @param monitor progress monitor
* @return array of .gitignore files modified during the unignore process
* @throws GitException an unexpected error occurs
*/
public File[] unignore (File[] files, ProgressMonitor monitor) throws GitException {
Repository repository = gitRepository.getRepository();
UnignoreCommand cmd = new UnignoreCommand(repository, getClassFactory(), files, monitor, delegateListener);
cmd.execute();
return cmd.getModifiedIgnoreFiles();
}
private GitClassFactory getClassFactory () {
if (gitFactory == null) {
gitFactory = GitClassFactoryImpl.getInstance();
}
return gitFactory;
}
private class DelegateListener implements StatusListener, FileListener, RevisionInfoListener {
@Override
public void notifyStatus (GitStatus status) {
GitClient.this.notifyStatus(status);
}
@Override
public void notifyFile (File file, String relativePathToRoot) {
GitClient.this.notifyFile(file, relativePathToRoot);
}
@Override
public void notifyRevisionInfo (GitRevisionInfo revisionInfo) {
GitClient.this.notifyRevisionInfo(revisionInfo);
}
}
//