Class Repository

  • Direct Known Subclasses:
    DfsRepository, FileRepository

    public abstract class Repository
    extends java.lang.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 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 java.io.IOException
        Create a new Git repository.

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

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

        public abstract 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 (a repository without a working directory) is created.
        Throws:
        java.io.IOException - in case of IO problem
      • getDirectory

        public java.io.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.
      • 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,
                                 java.io.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.
        java.io.IOException - the object store cannot be accessed.
      • 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.
      • updateRef

        public RefUpdate updateRef​(java.lang.String ref,
                                   boolean detach)
                            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.
        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:
        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 AmbiguousObjectException,
                                IncorrectObjectTypeException,
                                RevisionSyntaxException,
                                java.io.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.
        java.io.IOException - on serious errors
      • simplify

        public java.lang.String simplify​(java.lang.String revstr)
                                  throws AmbiguousObjectException,
                                         java.io.IOException
        Simplify an expression, but unlike resolve(String) it will not resolve a branch passed or resulting from the expression, such as @{-}. Thus this method can be used to process an expression to a method that expects a branch or revision id.
        Parameters:
        revstr -
        Returns:
        object id or ref name from resolved expression
        Throws:
        AmbiguousObjectException
        java.io.IOException
      • 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 java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • getFullBranch

        public java.lang.String getFullBranch()
                                       throws java.io.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:
        java.io.IOException
      • getBranch

        public java.lang.String getBranch()
                                   throws java.io.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:
        java.io.IOException
      • getAdditionalHaves

        public java.util.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​(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:
        mutable map of all known refs (heads, tags, remotes).
      • getTags

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

        public DirCache readDirCache()
                              throws NoWorkTreeException,
                                     CorruptObjectException,
                                     java.io.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().
        java.io.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,
                                     java.io.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().
        java.io.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​(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.
      • isBare

        public boolean isBare()
        Returns:
        true if this is bare, which implies it has no working directory.
      • getWorkTree

        public java.io.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 java.io.IOException
        Force a scan for changed refs.
        Throws:
        java.io.IOException
      • notifyIndexChanged

        public abstract void notifyIndexChanged()
        Notify that the index changed
      • shortenRefName

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

        public java.lang.String shortenRemoteBranchName​(java.lang.String refName)
        Parameters:
        refName -
        Returns:
        the remote branch name part of refName, i.e. without the refs/remotes/<remote> prefix, if refName represents a remote tracking branch; otherwise null.
        Since:
        3.4
      • getRemoteName

        public java.lang.String getRemoteName​(java.lang.String refName)
        Parameters:
        refName -
        Returns:
        the remote name part of refName, i.e. without the refs/remotes/<remote> prefix, if refName represents a remote tracking branch; otherwise null.
        Since:
        3.4
      • getReflogReader

        public abstract 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.
        Since:
        3.0
      • readMergeCommitMsg

        public java.lang.String readMergeCommitMsg()
                                            throws java.io.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:
        java.io.IOException
        NoWorkTreeException - if this is bare, which implies it has no working directory. See isBare().
      • writeMergeCommitMsg

        public void writeMergeCommitMsg​(java.lang.String msg)
                                 throws java.io.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:
        java.io.IOException
      • readMergeHeads

        public java.util.List<ObjectId> readMergeHeads()
                                                throws java.io.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:
        java.io.IOException
        NoWorkTreeException - if this is bare, which implies it has no working directory. See isBare().
      • writeMergeHeads

        public void writeMergeHeads​(java.util.List<? extends ObjectId> heads)
                             throws java.io.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:
        java.io.IOException
      • readCherryPickHead

        public ObjectId readCherryPickHead()
                                    throws java.io.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:
        java.io.IOException
        NoWorkTreeException - if this is bare, which implies it has no working directory. See isBare().
      • readRevertHead

        public ObjectId readRevertHead()
                                throws java.io.IOException,
                                       NoWorkTreeException
        Return the information stored in the file $GIT_DIR/REVERT_HEAD.
        Returns:
        object id from REVERT_HEAD file or null if this file doesn't exist. Also if the file exists but is empty null will be returned
        Throws:
        java.io.IOException
        NoWorkTreeException - if this is bare, which implies it has no working directory. See isBare().
      • writeCherryPickHead

        public void writeCherryPickHead​(ObjectId head)
                                 throws java.io.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:
        java.io.IOException
      • writeRevertHead

        public void writeRevertHead​(ObjectId head)
                             throws java.io.IOException
        Write revert commit into $GIT_DIR/REVERT_HEAD. This is used in case of conflicts to store the revert which was tried to be picked.
        Parameters:
        head - an object id of the revert commit or null to delete the file
        Throws:
        java.io.IOException
      • writeOrigHead

        public void writeOrigHead​(ObjectId head)
                           throws java.io.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:
        java.io.IOException
      • readOrigHead

        public ObjectId readOrigHead()
                              throws java.io.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:
        java.io.IOException
        NoWorkTreeException - if this is bare, which implies it has no working directory. See isBare().
      • readSquashCommitMsg

        public java.lang.String readSquashCommitMsg()
                                             throws java.io.IOException
        Return the information stored in the file $GIT_DIR/SQUASH_MSG. In this file operations triggering a squashed merge will store a template for the commit message of the squash commit.
        Returns:
        a String containing the content of the SQUASH_MSG file or null if this file doesn't exist
        Throws:
        java.io.IOException
        NoWorkTreeException - if this is bare, which implies it has no working directory. See isBare().
      • writeSquashCommitMsg

        public void writeSquashCommitMsg​(java.lang.String msg)
                                  throws java.io.IOException
        Write new content to the file $GIT_DIR/SQUASH_MSG. In this file operations triggering a squashed merge will store a template for the commit message of the squash 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:
        java.io.IOException
      • readRebaseTodo

        public java.util.List<RebaseTodoLine> readRebaseTodo​(java.lang.String path,
                                                             boolean includeComments)
                                                      throws java.io.IOException
        Read a file formatted like the git-rebase-todo file. The "done" file is also formatted like the git-rebase-todo file. These files can be found in .git/rebase-merge/ or .git/rebase-append/ folders.
        Parameters:
        path - path to the file relative to the repository's git-dir. E.g. "rebase-merge/git-rebase-todo" or "rebase-append/done"
        includeComments - true if also comments should be reported
        Returns:
        the list of steps
        Throws:
        java.io.IOException
        Since:
        3.2
      • writeRebaseTodoFile

        public void writeRebaseTodoFile​(java.lang.String path,
                                        java.util.List<RebaseTodoLine> steps,
                                        boolean append)
                                 throws java.io.IOException
        Write a file formatted like a git-rebase-todo file.
        Parameters:
        path - path to the file relative to the repository's git-dir. E.g. "rebase-merge/git-rebase-todo" or "rebase-append/done"
        steps - the steps to be written
        append - whether to append to an existing file or to write a new file
        Throws:
        java.io.IOException
        Since:
        3.2
      • getRemoteNames

        public java.util.Set<java.lang.String> getRemoteNames()
        Returns:
        the names of all known remotes
        Since:
        3.4