org.eclipse.jgit.lib
Class Repository

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

public class Repository
extends java.lang.Object

Represents a Git repository. A repository holds all objects and refs used for managing source code (could by any type of file, but source code is what SCM's are typically used for). In Git terms all data is stored in GIT_DIR, typically a directory called .git. A work tree is maintained unless the repository is a bare repository. Typically the .git directory is located at the root of the work dir.

This class is thread-safe.

This implementation only handles a subtly undocumented subset of git features.


Constructor Summary
Repository(java.io.File d)
          Construct a representation of a Git repository.
 
Method Summary
static void addAnyRepositoryChangedListener(RepositoryListener l)
          Register a global RepositoryListener which will be notified when a ref changes in any repository are detected.
 void addRepositoryChangedListener(RepositoryListener l)
          Register a RepositoryListener which will be notified when ref changes are detected.
 void close()
          Close all resources used by this repository
 void create()
          Create a new Git repository initializing the necessary files and directories.
 void create(boolean bare)
          Create a new Git repository initializing the necessary files and directories.
 java.util.Map<java.lang.String,Ref> getAllRefs()
           
 java.util.Map<AnyObjectId,java.util.Set<Ref>> getAllRefsByPeeledObjectId()
           
 java.lang.String getBranch()
           
 RepositoryConfig getConfig()
           
 java.io.File getDirectory()
           
 java.lang.String getFullBranch()
           
 GitIndex getIndex()
           
 ObjectDatabase getObjectDatabase()
           
 java.io.File getObjectsDirectory()
           
 Ref getRef(java.lang.String name)
          Get a ref by name.
 ReflogReader getReflogReader(java.lang.String refName)
           
 RepositoryState getRepositoryState()
           
 java.util.Map<java.lang.String,Ref> getTags()
           
 java.io.File getWorkDir()
           
 boolean hasObject(AnyObjectId objectId)
           
 void incrementOpen()
          Increment the use counter by one, requiring a matched close().
static boolean isValidRefName(java.lang.String refName)
          Check validity of a ref name.
 Commit mapCommit(ObjectId id)
          Access a Commit by SHA'1 id.
 Commit mapCommit(java.lang.String revstr)
          Access a Commit object using a symbolic reference.
 java.lang.Object mapObject(ObjectId id, java.lang.String refName)
          Access any type of Git object by id and
 Tag mapTag(java.lang.String revstr)
          Access a tag by symbolic name.
 Tag mapTag(java.lang.String refName, ObjectId id)
          Access a Tag by SHA'1 id
 Tree mapTree(ObjectId id)
          Access a Tree by SHA'1 id.
 Tree mapTree(java.lang.String revstr)
          Access a Tree object using a symbolic reference.
 ObjectLoader openBlob(ObjectId id)
           
 ObjectLoader openObject(AnyObjectId id)
           
 ObjectLoader openObject(WindowCursor curs, AnyObjectId id)
           
 java.util.Collection<org.eclipse.jgit.lib.PackedObjectLoader> openObjectInAllPacks(AnyObjectId objectId, WindowCursor curs)
          Open object in all packs containing specified object.
 void openPack(java.io.File pack, java.io.File idx)
          Add a single existing pack to the list of available pack files.
 ObjectLoader openTree(ObjectId id)
           
 Ref peel(Ref ref)
          Peel a possibly unpeeled ref and updates it.
 void refreshFromDisk()
          Clean up stale caches
static void removeAnyRepositoryChangedListener(RepositoryListener l)
          Remove a globally registered RepositoryListener
 void removeRepositoryChangedListener(RepositoryListener l)
          Remove a registered RepositoryListener
 RefRename renameRef(java.lang.String fromRef, java.lang.String toRef)
          Create a command to rename a ref in this repository
 ObjectId resolve(java.lang.String revstr)
          Parse a git revision string and return an object id.
 void scanForRepoChanges()
          Force a scan for changed refs.
 java.lang.String shortenRefName(java.lang.String refName)
           
static java.lang.String stripWorkDir(java.io.File workDir, java.io.File file)
          Strip work dir and return normalized repository path.
 java.io.File toFile(AnyObjectId objectId)
          Construct a filename where the loose object having a specified SHA-1 should be stored.
 java.lang.String toString()
           
 RefUpdate updateRef(java.lang.String ref)
          Create a command to update, create or delete a ref in this repository.
 void writeSymref(java.lang.String name, java.lang.String target)
          Writes a symref (e.g.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Repository

public Repository(java.io.File d)
           throws java.io.IOException
Construct a representation of a Git repository.

Parameters:
d - GIT_DIR (the location of the repository metadata).
Throws:
java.io.IOException - the repository appears to already exist but cannot be accessed.
Method Detail

create

public void create()
            throws java.io.IOException
Create a new Git repository initializing the necessary files and directories. Repository with working tree is created using this method.

Throws:
java.io.IOException
See Also:
create(boolean)

create

public void create(boolean bare)
            throws java.io.IOException
Create a new Git repository initializing the necessary files and directories.

Parameters:
bare - if true, a bare repository is created.
Throws:
java.io.IOException - in case of IO problem

getDirectory

public java.io.File getDirectory()
Returns:
GIT_DIR

getObjectsDirectory

public java.io.File getObjectsDirectory()
Returns:
the directory containing the objects owned by this repository.

getObjectDatabase

public ObjectDatabase getObjectDatabase()
Returns:
the object database which stores this repository's data.

getConfig

public RepositoryConfig getConfig()
Returns:
the configuration of this repository

toFile

public java.io.File toFile(AnyObjectId objectId)
Construct a filename where the loose object having a specified SHA-1 should be stored. If the object is stored in a shared repository the path to the alternative repo will be returned. If the object is not yet store a usable path in this repo will be returned. It is assumed that callers will look for objects in a pack first.

Parameters:
objectId -
Returns:
suggested file name

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.

openObject

public ObjectLoader openObject(AnyObjectId id)
                        throws java.io.IOException
Parameters:
id - SHA-1 of an object.
Returns:
a ObjectLoader for accessing the data of the named object, or null if the object does not exist.
Throws:
java.io.IOException

openObject

public ObjectLoader openObject(WindowCursor curs,
                               AnyObjectId id)
                        throws java.io.IOException
Parameters:
curs - temporary working space associated with the calling thread.
id - SHA-1 of an object.
Returns:
a ObjectLoader for accessing the data of the named object, or null if the object does not exist.
Throws:
java.io.IOException

openObjectInAllPacks

public java.util.Collection<org.eclipse.jgit.lib.PackedObjectLoader> openObjectInAllPacks(AnyObjectId objectId,
                                                                                          WindowCursor curs)
                                                                                   throws java.io.IOException
Open object in all packs containing specified object.

Parameters:
objectId - id of object to search for
curs - temporary working space associated with the calling thread.
Returns:
collection of loaders for this object, from all packs containing this object
Throws:
java.io.IOException

openBlob

public ObjectLoader openBlob(ObjectId id)
                      throws java.io.IOException
Parameters:
id - SHA'1 of a blob
Returns:
an ObjectLoader for accessing the data of a named blob
Throws:
java.io.IOException

openTree

public ObjectLoader openTree(ObjectId id)
                      throws java.io.IOException
Parameters:
id - SHA'1 of a tree
Returns:
an ObjectLoader for accessing the data of a named tree
Throws:
java.io.IOException

mapCommit

public Commit mapCommit(java.lang.String revstr)
                 throws java.io.IOException
Access a Commit object using a symbolic reference. This reference may be a SHA-1 or ref in combination with a number of symbols translating from one ref or SHA1-1 to another, such as HEAD^ etc.

Parameters:
revstr - a reference to a git commit object
Returns:
a Commit named by the specified string
Throws:
java.io.IOException - for I/O error or unexpected object type.
See Also:
resolve(String)

mapObject

public java.lang.Object mapObject(ObjectId id,
                                  java.lang.String refName)
                           throws java.io.IOException
Access any type of Git object by id and

Parameters:
id - SHA-1 of object to read
refName - optional, only relevant for simple tags
Returns:
The Git object if found or null
Throws:
java.io.IOException

mapCommit

public Commit mapCommit(ObjectId id)
                 throws java.io.IOException
Access a Commit by SHA'1 id.

Parameters:
id -
Returns:
Commit or null
Throws:
java.io.IOException - for I/O error or unexpected object type.

mapTree

public Tree mapTree(java.lang.String revstr)
             throws java.io.IOException
Access a Tree object using a symbolic reference. This reference may be a SHA-1 or ref in combination with a number of symbols translating from one ref or SHA1-1 to another, such as HEAD^{tree} etc.

Parameters:
revstr - a reference to a git commit object
Returns:
a Tree named by the specified string
Throws:
java.io.IOException
See Also:
resolve(String)

mapTree

public Tree mapTree(ObjectId id)
             throws java.io.IOException
Access a Tree by SHA'1 id.

Parameters:
id -
Returns:
Tree or null
Throws:
java.io.IOException - for I/O error or unexpected object type.

mapTag

public Tag mapTag(java.lang.String revstr)
           throws java.io.IOException
Access a tag by symbolic name.

Parameters:
revstr -
Returns:
a Tag or null
Throws:
java.io.IOException - on I/O error or unexpected type

mapTag

public Tag mapTag(java.lang.String refName,
                  ObjectId id)
           throws java.io.IOException
Access a Tag by SHA'1 id

Parameters:
refName -
id -
Returns:
Commit or null
Throws:
java.io.IOException - for I/O error or unexpected object type.

updateRef

public RefUpdate updateRef(java.lang.String ref)
                    throws java.io.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:
java.io.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(java.lang.String fromRef,
                           java.lang.String toRef)
                    throws java.io.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:
java.io.IOException - the rename could not be performed.

resolve

public ObjectId resolve(java.lang.String revstr)
                 throws java.io.IOException
Parse a git revision string and return an object id. Currently supported is combinations of these. Not supported is

Parameters:
revstr - A git object references expression
Returns:
an ObjectId or null if revstr can't be resolved to any ObjectId
Throws:
java.io.IOException - on serious errors

incrementOpen

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


close

public void close()
Close all resources used by this repository


openPack

public void openPack(java.io.File pack,
                     java.io.File idx)
              throws java.io.IOException
Add a single existing pack to the list of available pack files.

Parameters:
pack - path of the pack file to open.
idx - path of the corresponding index file.
Throws:
java.io.IOException - index file could not be opened, read, or is not recognized as a Git pack file index.

writeSymref

public void writeSymref(java.lang.String name,
                        java.lang.String target)
                 throws java.io.IOException
Writes a symref (e.g. HEAD) to disk

Parameters:
name - symref name
target - pointed to ref
Throws:
java.io.IOException

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

getFullBranch

public java.lang.String getFullBranch()
                               throws java.io.IOException
Returns:
name of current branch
Throws:
java.io.IOException

getBranch

public java.lang.String getBranch()
                           throws java.io.IOException
Returns:
name of current branch.
Throws:
java.io.IOException

getRef

public Ref getRef(java.lang.String name)
           throws java.io.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:
java.io.IOException

getAllRefs

public java.util.Map<java.lang.String,Ref> getAllRefs()
Returns:
all known refs (heads, tags, remotes).

getTags

public java.util.Map<java.lang.String,Ref> getTags()
Returns:
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 ref and updates it.

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 java.util.Map<AnyObjectId,java.util.Set<Ref>> getAllRefsByPeeledObjectId()
Returns:
a map with all objects referenced by a peeled ref.

refreshFromDisk

public void refreshFromDisk()
Clean up stale caches


getIndex

public GitIndex getIndex()
                  throws java.io.IOException
Returns:
a representation of the index associated with this repo
Throws:
java.io.IOException

getRepositoryState

public RepositoryState getRepositoryState()
Returns:
an important state

isValidRefName

public static boolean isValidRefName(java.lang.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 java.lang.String stripWorkDir(java.io.File workDir,
                                            java.io.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.

getWorkDir

public java.io.File getWorkDir()
Returns:
the workdir file, i.e. where the files are checked out

addRepositoryChangedListener

public void addRepositoryChangedListener(RepositoryListener l)
Register a RepositoryListener which will be notified when ref changes are detected.

Parameters:
l -

removeRepositoryChangedListener

public void removeRepositoryChangedListener(RepositoryListener l)
Remove a registered RepositoryListener

Parameters:
l -

addAnyRepositoryChangedListener

public static void addAnyRepositoryChangedListener(RepositoryListener l)
Register a global RepositoryListener which will be notified when a ref changes in any repository are detected.

Parameters:
l -

removeAnyRepositoryChangedListener

public static void removeAnyRepositoryChangedListener(RepositoryListener l)
Remove a globally registered RepositoryListener

Parameters:
l -

scanForRepoChanges

public void scanForRepoChanges()
                        throws java.io.IOException
Force a scan for changed refs.

Throws:
java.io.IOException

shortenRefName

public java.lang.String shortenRefName(java.lang.String refName)
Parameters:
refName -
Returns:
a more user friendly ref name

getReflogReader

public ReflogReader getReflogReader(java.lang.String refName)
                             throws java.io.IOException
Parameters:
refName -
Returns:
a ReflogReader for the supplied refname, or null if the named ref does not exist.
Throws:
java.io.IOException - the ref could not be accessed.