Package org.eclipse.jgit.internal.storage.file

Class RefDirectory

  • public class RefDirectory
extends RefDatabase
    Traditional file system based RefDatabase.

    This is the classical reference database representation for a Git repository. References are stored in two formats: loose, and packed.

    Loose references are stored as individual files within the refs/ directory. The file name matches the reference name and the file contents is the current ObjectId in string form.

    Packed references are stored in a single text file named packed-refs. In the packed format, each reference is stored on its own line. This file reduces the number of files needed for large reference spaces, reducing the overall size of a Git repository on disk.

    • Field Detail

      • LOG

        private static final org.slf4j.Logger LOG

      • SYMREF

        public static final java.lang.String SYMREF
        Magic string denoting the start of a symbolic reference file.
        See Also:
        Constant Field Values

      • PACKED_REFS_HEADER

        public static final java.lang.String PACKED_REFS_HEADER
        Magic string denoting the header of a packed-refs file.
        See Also:
        Constant Field Values

      • PACKED_REFS_PEELED

        public static final java.lang.String PACKED_REFS_PEELED
        If in the header, denotes the file has peeled data.
        See Also:
        Constant Field Values

      • additionalRefsNames

        private static final java.lang.String[] additionalRefsNames
        The names of the additional refs supported by this class

      • RETRY_SLEEP_MS

        private static final java.util.List<java.lang.Integer> RETRY_SLEEP_MS

      • gitDir

        private final java.io.File gitDir

      • refsDir

        final java.io.File refsDir

      • packedRefsFile

        final java.io.File packedRefsFile

      • logsDir

        final java.io.File logsDir

      • logsRefsDir

        final java.io.File logsRefsDir

      • looseRefs

        private final java.util.concurrent.atomic.AtomicReference<RefList<RefDirectory.LooseRef>> looseRefs
        Immutable sorted list of loose references.

        Symbolic references in this collection are stored unresolved, that is their target appears to be a new reference with no ObjectId. These are converted into resolved references during a get operation, ensuring the live value is always returned.

      • packedRefs

        final java.util.concurrent.atomic.AtomicReference<RefDirectory.PackedRefList> packedRefs
        Immutable sorted list of packed references.

      • inProcessPackedRefsLock

        final java.util.concurrent.locks.ReentrantLock inProcessPackedRefsLock
        Lock for coordinating operations within a single process that may contend on the packed-refs file.

        All operations that write packed-refs must still acquire a LockFile on packedRefsFile, even after they have acquired this lock, since there may be multiple RefDirectory instances or other processes operating on the same repo on disk.

        This lock exists so multiple threads in the same process can wait in a fair queue without trying, failing, and retrying to acquire the on-disk lock. If RepositoryCache is used, this lock instance will be used by all threads.

      • modCnt

        private final java.util.concurrent.atomic.AtomicInteger modCnt
        Number of modifications made to this database.

        This counter is incremented when a change is made, or detected from the filesystem during a read operation.

      • lastNotifiedModCnt

        private final java.util.concurrent.atomic.AtomicInteger lastNotifiedModCnt
        Last modCnt that we sent to listeners.

        This value is compared to modCnt, and a notification is sent to the listeners only when it differs.

      • retrySleepMs

        private java.util.List<java.lang.Integer> retrySleepMs

    • Method Detail

      • newLogWriter

        ReflogWriter newLogWriter​(boolean force)

      • logFor

        public java.io.File logFor​(java.lang.String name)
        Locate the log file on disk for a single reference name.
        Parameters:
        name - name of the ref, relative to the Git repository top level directory (so typically starts with refs/).
        Returns:
        the log file location.

      • create

        public void create()
            throws java.io.IOException
        Initialize a new reference database at this location.
        Specified by:
        create in class RefDatabase
        Throws:
        java.io.IOException - the database could not be created.

      • close

        public void close()
        Close any resources held by this database.
        Specified by:
        close in class RefDatabase

      • clearReferences

        private void clearReferences()

      • refresh

        public void refresh()
        Triggers a refresh of all internal data structures.

        In case the RefDatabase implementation has internal caches this method will trigger that all these caches are cleared.

        Implementors should overwrite this method if they use any kind of caches.

        Overrides:
        refresh in class RefDatabase

      • isNameConflicting

        public boolean isNameConflicting​(java.lang.String name)
                          throws java.io.IOException
        Determine if a proposed reference name overlaps with an existing one.

        Reference names use '/' as a component separator, and may be stored in a hierarchical storage such as a directory on the local filesystem.

        If the reference "refs/heads/foo" exists then "refs/heads/foo/bar" must not exist, as a reference cannot have a value and also be a container for other references at the same time.

        If the reference "refs/heads/foo/bar" exists than the reference "refs/heads/foo" cannot exist, for the same reason.

        Specified by:
        isNameConflicting in class RefDatabase
        Parameters:
        name - proposed name.
        Returns:
        true if the name overlaps with an existing reference; false if using this name right now would be safe.
        Throws:
        java.io.IOException - the database could not be read to check for conflicts.
        See Also:
        RefDatabase.getConflictingNames(String)

      • readAndResolve

        @Nullable
private Ref readAndResolve​(java.lang.String name,
                           RefList<Ref> packed)
                    throws java.io.IOException
        Throws:
        java.io.IOException

      • exactRef

        public Ref exactRef​(java.lang.String name)
             throws java.io.IOException
        Read a single reference.

        Unlike RefDatabase.findRef(java.lang.String), this method expects an unshortened reference name and does not search using the standard RefDatabase.SEARCH_PATH.

        Specified by:
        exactRef in class RefDatabase
        Parameters:
        name - the unabbreviated name of the reference.
        Returns:
        the reference (if it exists); else null.
        Throws:
        java.io.IOException - the reference space cannot be accessed.

      • exactRef

        @NonNull
public java.util.Map<java.lang.String,​Ref> exactRef​(java.lang.String... refs)
                                                   throws java.io.IOException
        Read the specified references.

        This method expects a list of unshortened reference names and returns a map from reference names to refs. Any named references that do not exist will not be included in the returned map.

        Overrides:
        exactRef in class RefDatabase
        Parameters:
        refs - the unabbreviated names of references to look up.
        Returns:
        modifiable map describing any refs that exist among the ref ref names supplied. The map can be an unsorted map.
        Throws:
        java.io.IOException - the reference space cannot be accessed.

      • firstExactRef

        @Nullable
public Ref firstExactRef​(java.lang.String... refs)
                  throws java.io.IOException
        Find the first named reference.

        This method expects a list of unshortened reference names and returns the first that exists.

        Overrides:
        firstExactRef in class RefDatabase
        Parameters:
        refs - the unabbreviated names of references to look up.
        Returns:
        the first named reference that exists (if any); else null.
        Throws:
        java.io.IOException - the reference space cannot be accessed.

      • getRefs

        public java.util.Map<java.lang.String,​Ref> getRefs​(java.lang.String prefix)
                                                  throws java.io.IOException
        Get a section of the reference namespace.
        Specified by:
        getRefs in class RefDatabase
        Parameters:
        prefix - prefix to search the namespace with; must end with /. If the empty string (RefDatabase.ALL), obtain a complete snapshot of all references.
        Returns:
        modifiable map that is a complete snapshot of the current reference namespace, with prefix removed from the start of each key. The map can be an unsorted map.
        Throws:
        java.io.IOException - the reference space cannot be accessed.

      • getAdditionalRefs

        public java.util.List<Ref> getAdditionalRefs()
                                      throws java.io.IOException
        Get the additional reference-like entities from the repository.

        The result list includes non-ref items such as MERGE_HEAD and FETCH_RESULT cast to be refs. The names of these refs are not returned by getRefs() but are accepted by RefDatabase.findRef(String) and RefDatabase.exactRef(String).

        Specified by:
        getAdditionalRefs in class RefDatabase
        Returns:
        a list of additional refs
        Throws:
        java.io.IOException - the reference space cannot be accessed.

      • peel

        public Ref peel​(Ref ref)
         throws java.io.IOException
        Peel a possibly unpeeled reference by traversing the annotated tags.

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

        Implementors should check Ref.isPeeled() before performing any additional work effort.

        Specified by:
        peel in class RefDatabase
        Parameters:
        ref - The reference to peel
        Returns:
        ref if ref.isPeeled() is true; otherwise a new Ref object representing the same data as Ref, but isPeeled() will be true and getPeeledObjectId() will contain the peeled object (or null).
        Throws:
        java.io.IOException - the reference space or object space cannot be accessed.

      • newUpdate

        public RefDirectoryUpdate newUpdate​(java.lang.String name,
                                    boolean detach)
                             throws java.io.IOException
        Create a new update command to create, modify or delete a reference.
        Specified by:
        newUpdate in class RefDatabase
        Parameters:
        name - the name of the reference.
        detach - if true and name is currently a SymbolicRef, the update will replace it with an ObjectIdRef. Otherwise, the update will recursively traverse SymbolicRefs and operate on the leaf ObjectIdRef.
        Returns:
        a new update for the requested name; never null.
        Throws:
        java.io.IOException - the reference space cannot be accessed.

      • newRename

        public RefDirectoryRename newRename​(java.lang.String fromName,
                                    java.lang.String toName)
                             throws java.io.IOException
        Create a new update command to rename a reference.
        Specified by:
        newRename in class RefDatabase
        Parameters:
        fromName - name of reference to rename from
        toName - name of reference to rename to
        Returns:
        an update command that knows how to rename a branch to another.
        Throws:
        java.io.IOException - the reference space cannot be accessed.

      • newBatchUpdate

        public PackedBatchRefUpdate newBatchUpdate()
        Create a new batch update to attempt on this database.

        The default implementation performs a sequential update of each command.

        Overrides:
        newBatchUpdate in class RefDatabase
        Returns:
        a new batch update object.

      • performsAtomicTransactions

        public boolean performsAtomicTransactions()
        Whether the database is capable of performing batch updates as atomic transactions.

        If true, by default BatchRefUpdate instances will perform updates atomically, meaning either all updates will succeed, or all updates will fail. It is still possible to turn off this behavior on a per-batch basis by calling update.setAtomic(false).

        If false, BatchRefUpdate instances will never perform updates atomically, and calling update.setAtomic(true) will cause the entire batch to fail with REJECTED_OTHER_REASON.

        This definition of atomicity is stronger than what is provided by ReceivePack. ReceivePack will attempt to reject all commands if it knows in advance some commands may fail, even if the storage layer does not support atomic transactions. Here, atomicity applies even in the case of unforeseeable errors.

        Overrides:
        performsAtomicTransactions in class RefDatabase
        Returns:
        whether transactions are atomic by default.

      • delete

        void delete​(RefDirectoryUpdate update)
     throws java.io.IOException
        Throws:
        java.io.IOException

      • pack

        public void pack​(java.util.List<java.lang.String> refs)
          throws java.io.IOException
        Adds a set of refs to the set of packed-refs. Only non-symbolic refs are added. If a ref with the given name already existed in packed-refs it is updated with the new value. Each loose ref which was added to the packed-ref file is deleted. If a given ref can't be locked it will not be added to the pack file.
        Parameters:
        refs - the refs to be added. Must be fully qualified.
        Throws:
        java.io.IOException

      • pack

        private RefDirectory.PackedRefList pack​(java.util.Collection<java.lang.String> refs,
                                        java.util.Map<java.lang.String,​LockFile> heldLocks)
                                 throws java.io.IOException
        Throws:
        java.io.IOException

      • lockPackedRefs

        @Nullable
LockFile lockPackedRefs()
                 throws java.io.IOException
        Throws:
        java.io.IOException

      • lockPackedRefsOrThrow

        private LockFile lockPackedRefsOrThrow()
                                throws java.io.IOException
        Throws:
        java.io.IOException

      • peeledPackedRef

        private Ref peeledPackedRef​(Ref f)
                     throws MissingObjectException,
                            java.io.IOException
        Make sure a ref is peeled and has the Storage PACKED. If the given ref has this attributes simply return it. Otherwise create a new peeled ObjectIdRef where Storage is set to PACKED.
        Parameters:
        f -
        Returns:
        a ref for Storage PACKED having the same name, id, peeledId as f
        Throws:
        MissingObjectException
        java.io.IOException

      • log

        void log​(boolean force,
         RefUpdate update,
         java.lang.String msg,
         boolean deref)
  throws java.io.IOException
        Throws:
        java.io.IOException

      • parsePackedRefs

        private RefList<Ref> parsePackedRefs​(java.io.BufferedReader br)
                              throws java.io.IOException
        Throws:
        java.io.IOException

      • copy

        private static java.lang.String copy​(java.lang.String src,
                                     int off,
                                     int end)

      • readRef

        private Ref readRef​(java.lang.String name,
                    RefList<Ref> packed)
             throws java.io.IOException
        Throws:
        java.io.IOException

      • isSymRef

        private static boolean isSymRef​(byte[] buf,
                                int n)

      • isInClone

        boolean isInClone()
           throws java.io.IOException
        Detect if we are in a clone command execution
        Returns:
        true if we are currently cloning a repository
        Throws:
        java.io.IOException

      • hasDanglingHead

        private boolean hasDanglingHead()
                         throws java.io.IOException
        Throws:
        java.io.IOException

      • hasLooseRef

        private boolean hasLooseRef()
                     throws java.io.IOException
        Throws:
        java.io.IOException

      • fireRefsChanged

        void fireRefsChanged()
        If the parent should fire listeners, fires them.

      • newTemporaryUpdate

        RefDirectoryUpdate newTemporaryUpdate()
                               throws java.io.IOException
        Create a reference update to write a temporary reference.
        Returns:
        an update for a new temporary reference.
        Throws:
        java.io.IOException - a temporary name cannot be allocated.

      • fileFor

        java.io.File fileFor​(java.lang.String name)
        Locate the file on disk for a single reference name.
        Parameters:
        name - name of the ref, relative to the Git repository top level directory (so typically starts with refs/).
        Returns:
        the loose file location.

      • levelsIn

        static int levelsIn​(java.lang.String name)

      • delete

        static void delete​(java.io.File file,
                   int depth)
            throws java.io.IOException
        Throws:
        java.io.IOException

      • delete

        private static void delete​(java.io.File file,
                           int depth,
                           LockFile rLck)
                    throws java.io.IOException
        Throws:
        java.io.IOException

      • getRetrySleepMs

        java.lang.Iterable<java.lang.Integer> getRetrySleepMs()
        Get times to sleep while retrying a possibly contentious operation.

        For retrying an operation that might have high contention, such as locking the packed-refs file, the caller may implement a retry loop using the returned values: 

         for (int toSleepMs : getRetrySleepMs()) {
   sleep(toSleepMs);
   if (isSuccessful(doSomething())) {
     return success;
   }
 }
 return failure;
        The first value in the returned iterable is 0, and the caller should treat a fully-consumed iterator as a timeout.
        Returns:
        iterable of times, in milliseconds, that the caller should sleep before attempting an operation.

      • setRetrySleepMs

        void setRetrySleepMs​(java.util.List<java.lang.Integer> retrySleepMs)

      • sleep

        static void sleep​(long ms)
           throws java.io.InterruptedIOException
        Sleep with Thread.sleep(long), converting InterruptedException to InterruptedIOException.
        Parameters:
        ms - time to sleep, in milliseconds; zero or negative is a no-op.
        Throws:
        java.io.InterruptedIOException - if sleeping was interrupted.