org.eclipse.jgit.lib
Class Repository

java.lang.Object
  org.eclipse.jgit.lib.Repository

Direct Known Subclasses:

DfsRepository, FileRepository

public abstract class Repository
extends Object

Represents a Git repository.

A repository holds all objects and refs used for managing source code (could be any type of file, but source code is what SCM's are typically used for).

This class is thread-safe.

Constructor Summary

protected

Repository(BaseRepositoryBuilder options) Initialize a new repository instance.

Method Summary

void	close() Decrement the use count, and maybe close resources.
void	create() Create a new Git repository.
abstract void	create(boolean bare) Create a new Git repository initializing the necessary files and directories.
protected void	doClose() Invoked when the use count drops to zero during close().
void	fireEvent(RepositoryEvent<?> event) Fire an event to all registered listeners.
Set<ObjectId>	getAdditionalHaves() Objects known to exist but not expressed by getAllRefs().
Map<String,Ref>	getAllRefs()
Map<AnyObjectId,Set<Ref>>	getAllRefsByPeeledObjectId()
String	getBranch() Get the short name of the current branch that HEAD points to.
abstract StoredConfig	getConfig()
File	getDirectory()
FS	getFS()
String	getFullBranch() Get the name of the reference that HEAD points to.
static ListenerList	getGlobalListenerList()
File	getIndexFile()
ListenerList	getListenerList()
abstract ObjectDatabase	getObjectDatabase()
Ref	getRef(String name) Get a ref by name.
abstract RefDatabase	getRefDatabase()
abstract ReflogReader	getReflogReader(String refName)
RepositoryState	getRepositoryState()
Map<String,Ref>	getTags()
File	getWorkTree()
boolean	hasObject(AnyObjectId objectId)
void	incrementOpen() Increment the use counter by one, requiring a matched close().
boolean	isBare()
static boolean	isValidRefName(String refName) Check validity of a ref name.
DirCache	lockDirCache() Create a new in-core index representation, lock it, and read from disk.
ObjectInserter	newObjectInserter()
ObjectReader	newObjectReader()
abstract void	notifyIndexChanged() Notify that the index changed
ObjectLoader	open(AnyObjectId objectId) Open an object from this repository.
ObjectLoader	open(AnyObjectId objectId, int typeHint) Open an object from this repository.
Ref	peel(Ref ref) Peel a possibly unpeeled reference to an annotated tag.
ObjectId	readCherryPickHead() Return the information stored in the file $GIT_DIR/CHERRY_PICK_HEAD.
DirCache	readDirCache() Create a new in-core index representation and read an index from disk.
String	readMergeCommitMsg() Return the information stored in the file $GIT_DIR/MERGE_MSG.
List<ObjectId>	readMergeHeads() Return the information stored in the file $GIT_DIR/MERGE_HEAD.
ObjectId	readOrigHead() Return the information stored in the file $GIT_DIR/ORIG_HEAD.
RefRename	renameRef(String fromRef, String toRef) Create a command to rename a ref in this repository
ObjectId	resolve(String revstr) Parse a git revision string and return an object id.
abstract void	scanForRepoChanges() Force a scan for changed refs.
static String	shortenRefName(String refName)
static String	stripWorkDir(File workDir, File file) Strip work dir and return normalized repository path.
String	toString()
RefUpdate	updateRef(String ref) Create a command to update, create or delete a ref in this repository.
RefUpdate	updateRef(String ref, boolean detach) Create a command to update, create or delete a ref in this repository.
void	writeCherryPickHead(ObjectId head) Write cherry pick commit into $GIT_DIR/CHERRY_PICK_HEAD.
void	writeMergeCommitMsg(String msg) Write new content to the file $GIT_DIR/MERGE_MSG.
void	writeMergeHeads(List<ObjectId> heads) Write new merge-heads into $GIT_DIR/MERGE_HEAD.
void	writeOrigHead(ObjectId head) Write original HEAD commit into $GIT_DIR/ORIG_HEAD.

Methods inherited from class java.lang.Object

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

Constructor Detail

Repository

protected Repository(BaseRepositoryBuilder options)

Initialize a new repository instance.

Parameters:

options - options to configure the repository.

Method Detail

getGlobalListenerList

public static ListenerList getGlobalListenerList()

Returns:

the global listener list observing all events in this JVM.

getListenerList

public ListenerList getListenerList()

Returns:

listeners observing only events on this repository.

fireEvent

public void fireEvent(RepositoryEvent<?> event)

Fire an event to all registered listeners.

The source repository of the event is automatically set to this repository, before the event is delivered to any listeners.

Parameters:

event - the event to deliver.

create

public void create()
            throws IOException

Create a new Git repository.

Repository with working tree is created using this method. This method is the same as create(false).

Throws:

IOException

See Also:

create(boolean)

create

public abstract void create(boolean bare)
                     throws IOException

Create a new Git repository initializing the necessary files and directories.

Parameters:

bare - if true, a bare repository (a repository without a working directory) is created.

Throws:

IOException - in case of IO problem

getDirectory

public File getDirectory()

Returns:

local metadata directory; null if repository isn't local.

getObjectDatabase

public abstract ObjectDatabase getObjectDatabase()

Returns:

the object database which stores this repository's data.

newObjectInserter

public ObjectInserter newObjectInserter()

Returns:

a new inserter to create objects in getObjectDatabase()

newObjectReader

public ObjectReader newObjectReader()

Returns:

a new reader to read objects from getObjectDatabase()

getRefDatabase

public abstract RefDatabase getRefDatabase()

Returns:

the reference database which stores the reference namespace.

getConfig

public abstract StoredConfig getConfig()

Returns:

the configuration of this repository

getFS

public FS getFS()

Returns:

the used file system abstraction

hasObject

public boolean hasObject(AnyObjectId objectId)

Parameters:

objectId -

Returns:

true if the specified object is stored in this repo or any of the known shared repositories.

open

public ObjectLoader open(AnyObjectId objectId)
                  throws MissingObjectException,
                         IOException

Open an object from this repository.

This is a one-shot call interface which may be faster than allocating a newObjectReader() to perform the lookup.

Parameters:

objectId - identity of the object to open.

Returns:

a ObjectLoader for accessing the object.

Throws:

MissingObjectException - the object does not exist.

IOException - the object store cannot be accessed.

open

public ObjectLoader open(AnyObjectId objectId,
                         int typeHint)
                  throws MissingObjectException,
                         IncorrectObjectTypeException,
                         IOException

Open an object from this repository.

This is a one-shot call interface which may be faster than allocating a newObjectReader() to perform the lookup.

Parameters:

objectId - identity of the object to open.

typeHint - hint about the type of object being requested; ObjectReader.OBJ_ANY if the object type is not known, or does not matter to the caller.

Returns:

a ObjectLoader for accessing the object.

Throws:

MissingObjectException - the object does not exist.

IncorrectObjectTypeException - typeHint was not OBJ_ANY, and the object's actual type does not match typeHint.

IOException - the object store cannot be accessed.

updateRef

public RefUpdate updateRef(String ref)
                    throws IOException

Create a command to update, create or delete a ref in this repository.

Parameters:

ref - name of the ref the caller wants to modify.

Returns:

an update command. The caller must finish populating this command and then invoke one of the update methods to actually make a change.

Throws:

IOException - a symbolic ref was passed in and could not be resolved back to the base ref, as the symbolic ref could not be read.

updateRef

public RefUpdate updateRef(String ref,
                           boolean detach)
                    throws IOException

Create a command to update, create or delete a ref in this repository.

Parameters:

ref - name of the ref the caller wants to modify.

detach - true to create a detached head

Returns:

an update command. The caller must finish populating this command and then invoke one of the update methods to actually make a change.

Throws:

IOException - a symbolic ref was passed in and could not be resolved back to the base ref, as the symbolic ref could not be read.

renameRef

public RefRename renameRef(String fromRef,
                           String toRef)
                    throws IOException

Create a command to rename a ref in this repository

Parameters:

fromRef - name of ref to rename from

toRef - name of ref to rename to

Returns:

an update command that knows how to rename a branch to another.

Throws:

IOException - the rename could not be performed.

resolve

public ObjectId resolve(String revstr)
                 throws AmbiguousObjectException,
                        IOException

Parse a git revision string and return an object id. Combinations of these operators are supported:

• HEAD, MERGE_HEAD, FETCH_HEAD
• SHA-1: a complete or abbreviated SHA-1
• refs/...: a complete reference name
• short-name: a short reference name under refs/heads, refs/tags, or refs/remotes namespace
• tag-NN-gABBREV: output from describe, parsed by treating ABBREV as an abbreviated SHA-1.
• id^: first parent of commit id, this is the same as id^1
• id^0: ensure id is a commit
• id^n: n-th parent of commit id
• id~n: n-th historical ancestor of id, by first parent. id~3 is equivalent to id^1^1^1 or id^^^.
• id:path: Lookup path under tree named by id
• id^{commit}: ensure id is a commit
• id^{tree}: ensure id is a tree
• id^{tag}: ensure id is a tag
• id^{blob}: ensure id is a blob

The following operators are specified by Git conventions, but are not supported by this method:

• ref@{n}: n-th version of ref as given by its reflog
• ref@{time}: value of ref at the designated time

Parameters:

revstr - A git object references expression

Returns:

an ObjectId or null if revstr can't be resolved to any ObjectId

Throws:

AmbiguousObjectException - revstr contains an abbreviated ObjectId and this repository contains more than one object which match to the input abbreviation.

IncorrectObjectTypeException - the id parsed does not meet the type required to finish applying the operators in the expression.

RevisionSyntaxException - the expression is not supported by this implementation, or does not meet the standard syntax.

IOException - on serious errors

incrementOpen

public void incrementOpen()

Increment the use counter by one, requiring a matched close().

close

public void close()

Decrement the use count, and maybe close resources.

doClose

protected void doClose()

Invoked when the use count drops to zero during close().

The default implementation closes the object and ref databases.

toString

public String toString()

Overrides:

toString in class Object

getFullBranch

public String getFullBranch()
                     throws IOException

Get the name of the reference that HEAD points to.

This is essentially the same as doing:

 return getRef(Constants.HEAD).getTarget().getName()
 

Except when HEAD is detached, in which case this method returns the current ObjectId in hexadecimal string format.

Returns:

name of current branch (for example refs/heads/master) or an ObjectId in hex format if the current branch is detached.

Throws:

IOException

getBranch

public String getBranch()
                 throws IOException

Get the short name of the current branch that HEAD points to.

This is essentially the same as getFullBranch(), except the leading prefix refs/heads/ is removed from the reference before it is returned to the caller.

Returns:

name of current branch (for example master), or an ObjectId in hex format if the current branch is detached.

Throws:

IOException

getAdditionalHaves

public Set<ObjectId> getAdditionalHaves()

Objects known to exist but not expressed by getAllRefs().

When a repository borrows objects from another repository, it can advertise that it safely has that other repository's references, without exposing any other details about the other repository. This may help a client trying to push changes avoid pushing more than it needs to.

Returns:

unmodifiable collection of other known objects.

getRef

public Ref getRef(String name)
           throws IOException

Get a ref by name.

Parameters:

name - the name of the ref to lookup. May be a short-hand form, e.g. "master" which is is automatically expanded to "refs/heads/master" if "refs/heads/master" already exists.

Returns:

the Ref with the given name, or null if it does not exist

Throws:

IOException

getAllRefs

public Map<String,Ref> getAllRefs()

Returns:

mutable map of all known refs (heads, tags, remotes).

getTags

public Map<String,Ref> getTags()

Returns:

mutable map of all tags; key is short tag name ("v1.0") and value of the entry contains the ref with the full tag name ("refs/tags/v1.0").

peel

public Ref peel(Ref ref)

Peel a possibly unpeeled reference to an annotated tag.

If the ref cannot be peeled (as it does not refer to an annotated tag) the peeled id stays null, but Ref.isPeeled() will be true.

Parameters:

ref - The ref to peel

Returns:

ref if ref.isPeeled() is true; else a new Ref object representing the same data as Ref, but isPeeled() will be true and getPeeledObjectId will contain the peeled object (or null).

getAllRefsByPeeledObjectId

public Map<AnyObjectId,Set<Ref>> getAllRefsByPeeledObjectId()

Returns:

a map with all objects referenced by a peeled ref.

getIndexFile

public File getIndexFile()
                  throws NoWorkTreeException

Returns:

the index file location

Throws:

NoWorkTreeException - if this is bare, which implies it has no working directory. See isBare().

readDirCache

public DirCache readDirCache()
                      throws NoWorkTreeException,
                             CorruptObjectException,
                             IOException

Create a new in-core index representation and read an index from disk.

The new index will be read before it is returned to the caller. Read failures are reported as exceptions and therefore prevent the method from returning a partially populated index.

Returns:

a cache representing the contents of the specified index file (if it exists) or an empty cache if the file does not exist.

Throws:

NoWorkTreeException - if this is bare, which implies it has no working directory. See isBare().

IOException - the index file is present but could not be read.

CorruptObjectException - the index file is using a format or extension that this library does not support.

lockDirCache

public DirCache lockDirCache()
                      throws NoWorkTreeException,
                             CorruptObjectException,
                             IOException

Create a new in-core index representation, lock it, and read from disk.

The new index will be locked and then read before it is returned to the caller. Read failures are reported as exceptions and therefore prevent the method from returning a partially populated index.

Returns:

a cache representing the contents of the specified index file (if it exists) or an empty cache if the file does not exist.

Throws:

NoWorkTreeException - if this is bare, which implies it has no working directory. See isBare().

IOException - the index file is present but could not be read, or the lock could not be obtained.

CorruptObjectException - the index file is using a format or extension that this library does not support.

getRepositoryState

public RepositoryState getRepositoryState()

Returns:

an important state

isValidRefName

public static boolean isValidRefName(String refName)

Check validity of a ref name. It must not contain character that has a special meaning in a Git object reference expression. Some other dangerous characters are also excluded. For portability reasons '\' is excluded

Parameters:

refName -

Returns:

true if refName is a valid ref name

stripWorkDir

public static String stripWorkDir(File workDir,
                                  File file)

Strip work dir and return normalized repository path.

Parameters:

workDir - Work dir

file - File whose path shall be stripped of its workdir

Returns:

normalized repository relative path or the empty string if the file is not relative to the work directory.

isBare

public boolean isBare()

Returns:

true if this is bare, which implies it has no working directory.

getWorkTree

public File getWorkTree()
                 throws NoWorkTreeException

Returns:

the root directory of the working tree, where files are checked out for viewing and editing.

Throws:

NoWorkTreeException - if this is bare, which implies it has no working directory. See isBare().

scanForRepoChanges

public abstract void scanForRepoChanges()
                                 throws IOException

Force a scan for changed refs.

Throws:

IOException

notifyIndexChanged

public abstract void notifyIndexChanged()

Notify that the index changed

shortenRefName

public static String shortenRefName(String refName)

Parameters:

refName -

Returns:

a more user friendly ref name

getReflogReader

public abstract ReflogReader getReflogReader(String refName)
                                      throws IOException

Parameters:

refName -

Returns:

a ReflogReader for the supplied refname, or null if the named ref does not exist.

Throws:

IOException - the ref could not be accessed.

readMergeCommitMsg

public String readMergeCommitMsg()
                          throws IOException,
                                 NoWorkTreeException

Return the information stored in the file $GIT_DIR/MERGE_MSG. In this file operations triggering a merge will store a template for the commit message of the merge commit.

Returns:

a String containing the content of the MERGE_MSG file or null if this file doesn't exist

Throws:

IOException

NoWorkTreeException - if this is bare, which implies it has no working directory. See isBare().

writeMergeCommitMsg

public void writeMergeCommitMsg(String msg)
                         throws IOException

Write new content to the file $GIT_DIR/MERGE_MSG. In this file operations triggering a merge will store a template for the commit message of the merge commit. If null is specified as message the file will be deleted

Parameters:

msg - the message which should be written or null to delete the file

Throws:

IOException

readMergeHeads

public List<ObjectId> readMergeHeads()
                              throws IOException,
                                     NoWorkTreeException

Return the information stored in the file $GIT_DIR/MERGE_HEAD. In this file operations triggering a merge will store the IDs of all heads which should be merged together with HEAD.

Returns:

a list of commits which IDs are listed in the MERGE_HEAD file or null if this file doesn't exist. Also if the file exists but is empty null will be returned

Throws:

IOException

NoWorkTreeException - if this is bare, which implies it has no working directory. See isBare().

writeMergeHeads

public void writeMergeHeads(List<ObjectId> heads)
                     throws IOException

Write new merge-heads into $GIT_DIR/MERGE_HEAD. In this file operations triggering a merge will store the IDs of all heads which should be merged together with HEAD. If null is specified as list of commits the file will be deleted

Parameters:

heads - a list of commits which IDs should be written to $GIT_DIR/MERGE_HEAD or null to delete the file

Throws:

IOException

readCherryPickHead

public ObjectId readCherryPickHead()
                            throws IOException,
                                   NoWorkTreeException

Return the information stored in the file $GIT_DIR/CHERRY_PICK_HEAD.

Returns:

object id from CHERRY_PICK_HEAD file or null if this file doesn't exist. Also if the file exists but is empty null will be returned

Throws:

IOException

NoWorkTreeException - if this is bare, which implies it has no working directory. See isBare().

writeCherryPickHead

public void writeCherryPickHead(ObjectId head)
                         throws IOException

Write cherry pick commit into $GIT_DIR/CHERRY_PICK_HEAD. This is used in case of conflicts to store the cherry which was tried to be picked.

Parameters:

head - an object id of the cherry commit or null to delete the file

Throws:

IOException

writeOrigHead

public void writeOrigHead(ObjectId head)
                   throws IOException

Write original HEAD commit into $GIT_DIR/ORIG_HEAD.

Parameters:

head - an object id of the original HEAD commit or null to delete the file

Throws:

IOException

readOrigHead

public ObjectId readOrigHead()
                      throws IOException,
                             NoWorkTreeException

Return the information stored in the file $GIT_DIR/ORIG_HEAD.

Returns:

object id from ORIG_HEAD file or null if this file doesn't exist. Also if the file exists but is empty null will be returned

Throws:

IOException

NoWorkTreeException - if this is bare, which implies it has no working directory. See isBare().