Class RefDirectory

java.lang.Object
org.eclipse.jgit.lib.RefDatabase
org.eclipse.jgit.internal.storage.file.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 Details

    • SYMREF

      public static final String SYMREF
      Magic string denoting the start of a symbolic reference file.
      See Also:
    • PACKED_REFS_HEADER

      public static final String PACKED_REFS_HEADER
      Magic string denoting the header of a packed-refs file.
      See Also:
    • PACKED_REFS_PEELED

      public static final String PACKED_REFS_PEELED
      If in the header, denotes the file has peeled data.
      See Also:
  • Method Details

    • logFor

      public File logFor(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.
    • createSnapshottingRefDirectory

      public org.eclipse.jgit.internal.storage.file.SnapshottingRefDirectory createSnapshottingRefDirectory()
      Create a cache of this RefDirectory.
      Returns:
      a cached RefDirectory.
    • create

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

      public void close()
      Description copied from class: RefDatabase
      Close any resources held by this database.
      Specified by:
      close in class RefDatabase
    • refresh

      public void refresh()
      Description copied from class: RefDatabase
      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(String name) throws IOException
      Description copied from class: RefDatabase
      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:
      IOException - the database could not be read to check for conflicts.
      See Also:
    • exactRef

      public Ref exactRef(String name) throws IOException
      Description copied from class: RefDatabase
      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:
      IOException - the reference space cannot be accessed.
    • exactRef

      @NonNull public Map<String,Ref> exactRef(String... refs) throws IOException
      Description copied from class: RefDatabase
      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:
      IOException - the reference space cannot be accessed.
    • firstExactRef

      @Nullable public Ref firstExactRef(String... refs) throws IOException
      Description copied from class: RefDatabase
      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:
      IOException - the reference space cannot be accessed.
    • getRefs

      public Map<String,Ref> getRefs(String prefix) throws IOException
      Description copied from class: RefDatabase
      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:
      IOException - the reference space cannot be accessed.
    • getRefsByPrefix

      public List<Ref> getRefsByPrefix(String... prefixes) throws IOException
      Description copied from class: RefDatabase
      Returns refs whose names start with one of the given prefixes.

      The default implementation uses RefDatabase.getRefsByPrefix(String). Implementors of RefDatabase should override this method directly if a better implementation is possible.

      Overrides:
      getRefsByPrefix in class RefDatabase
      Parameters:
      prefixes - strings that names of refs should start with.
      Returns:
      immutable list of refs whose names start with one of prefixes. Refs can be unsorted and may contain duplicates if the prefixes overlap.
      Throws:
      IOException - the reference space cannot be accessed.
    • getAdditionalRefs

      public List<Ref> getAdditionalRefs() throws IOException
      Description copied from class: RefDatabase
      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:
      IOException - the reference space cannot be accessed.
    • peel

      public Ref peel(Ref ref) throws IOException
      Description copied from class: RefDatabase
      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:
      IOException - the reference space or object space cannot be accessed.
    • newUpdate

      public org.eclipse.jgit.internal.storage.file.RefDirectoryUpdate newUpdate(String name, boolean detach) throws IOException
      Description copied from class: RefDatabase
      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:
      IOException - the reference space cannot be accessed.
    • newRename

      public org.eclipse.jgit.internal.storage.file.RefDirectoryRename newRename(String fromName, String toName) throws IOException
      Description copied from class: RefDatabase
      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:
      IOException - the reference space cannot be accessed.
    • newBatchUpdate

      public org.eclipse.jgit.internal.storage.file.PackedBatchRefUpdate newBatchUpdate()
      Description copied from class: RefDatabase
      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.
    • newBatchUpdate

      public org.eclipse.jgit.internal.storage.file.PackedBatchRefUpdate newBatchUpdate(boolean shouldLockLooseRefs)
      Create a new batch update to attempt on this database.
      Parameters:
      shouldLockLooseRefs - whether loose refs should be locked during the batch ref update. Note that this should only be set to false if the application using this ensures that no other ref updates run concurrently to avoid lost updates caused by a race. In such cases it can improve performance.
      Returns:
      a new batch update object
    • performsAtomicTransactions

      public boolean performsAtomicTransactions()
      Description copied from class: RefDatabase
      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.
    • pack

      public void pack(List<String> refs) throws 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:
      IOException - if an IO error occurred