org.eclipse.jgit.internal.storage.file

## 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 Summary

Fields
`static String` `PACKED_REFS_HEADER` Magic string denoting the header of a packed-refs file.
`static String` `PACKED_REFS_PEELED` If in the header, denotes the file has peeled data.
`static String` `SYMREF` Magic string denoting the start of a symbolic reference file.

### Fields inherited from class org.eclipse.jgit.lib.RefDatabase

`ALL, MAX_SYMBOLIC_REF_DEPTH, SEARCH_PATH`

### Method Summary

Methods
`void` `close()` Close any resources held by this database.
`void` `create()` Initialize a new reference database at this location.
`List<Ref>` `getAdditionalRefs()` Get the additional reference-like entities from the repository.
`Ref` `getRef(String needle)` Read a single reference.
`Map<String,Ref>` `getRefs(String prefix)` Get a section of the reference namespace.
`boolean` `isNameConflicting(String name)` Determine if a proposed reference name overlaps with an existing one.
`org.eclipse.jgit.internal.storage.file.RefDirectoryRename` `newRename(String fromName, String toName)` Create a new update command to rename a reference.
`org.eclipse.jgit.internal.storage.file.RefDirectoryUpdate` `newUpdate(String name, boolean detach)` Create a new update command to create, modify or delete a reference.
`void` `pack(List<String> refs)` Adds a set of refs to the set of packed-refs.
`Ref` `peel(Ref ref)` Peel a possibly unpeeled reference by traversing the annotated tags.
`void` `refresh()` Triggers a refresh of all internal data structures.

### Methods inherited from class org.eclipse.jgit.lib.RefDatabase

`getConflictingNames, newBatchUpdate`

### Methods inherited from class java.lang.Object

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

### Field Detail

#### SYMREF

    public static final String SYMREF

Magic string denoting the start of a symbolic reference file.

See Also:
  Constant Field Values

#### PACKED_REFS_HEADER

    public static final 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 String PACKED_REFS_PEELED

If in the header, denotes the file has peeled data.

See Also:
  Constant Field Values

### Method Detail

#### 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:
  `RefDatabase.getConflictingNames(String)`

#### getRef

    public Ref getRef(String needle)
               throws IOException

Description copied from class: `RefDatabase`
Read a single reference.

Aside from taking advantage of `RefDatabase.SEARCH_PATH`, this method may be able to more quickly resolve a single reference name than obtaining the complete namespace by `getRefs(ALL).get(name)`.

Specified by:
  `getRef` in class `RefDatabase`
Parameters:
  `needle` - the name of the reference. May be a short name which must be searched for using the standard `RefDatabase.SEARCH_PATH`.
Returns:
  the reference (if it exists); 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.

#### 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(ALL)` but are accepted by `RefDatabase.getRef(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 `SymbolicRef`s 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.

#### 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`