| /* |
| * Copyright (C) 2006-2008, Shawn O. Pearce <spearce@spearce.org> and others |
| * |
| * This program and the accompanying materials are made available under the |
| * terms of the Eclipse Distribution License v. 1.0 which is available at |
| * https://www.eclipse.org/org/documents/edl-v10.php. |
| * |
| * SPDX-License-Identifier: BSD-3-Clause |
| */ |
| |
| package org.eclipse.jgit.lib; |
| |
| import org.eclipse.jgit.annotations.NonNull; |
| import org.eclipse.jgit.annotations.Nullable; |
| |
| /** |
| * Pairing of a name and the {@link org.eclipse.jgit.lib.ObjectId} it currently |
| * has. |
| * <p> |
| * A ref in Git is (more or less) a variable that holds a single object |
| * identifier. The object identifier can be any valid Git object (blob, tree, |
| * commit, annotated tag, ...). |
| * <p> |
| * The ref name has the attributes of the ref that was asked for as well as the |
| * ref it was resolved to for symbolic refs plus the object id it points to and |
| * (for tags) the peeled target object id, i.e. the tag resolved recursively |
| * until a non-tag object is referenced. |
| */ |
| public interface Ref { |
| /** Location where a {@link Ref} is stored. */ |
| enum Storage { |
| /** |
| * The ref does not exist yet, updating it may create it. |
| * <p> |
| * Creation is likely to choose {@link #LOOSE} storage. |
| */ |
| NEW(true, false), |
| |
| /** |
| * The ref is stored in a file by itself. |
| * <p> |
| * Updating this ref affects only this ref. |
| */ |
| LOOSE(true, false), |
| |
| /** |
| * The ref is stored in the <code>packed-refs</code> file, with others. |
| * <p> |
| * Updating this ref requires rewriting the file, with perhaps many |
| * other refs being included at the same time. |
| */ |
| PACKED(false, true), |
| |
| /** |
| * The ref is both {@link #LOOSE} and {@link #PACKED}. |
| * <p> |
| * Updating this ref requires only updating the loose file, but deletion |
| * requires updating both the loose file and the packed refs file. |
| */ |
| LOOSE_PACKED(true, true), |
| |
| /** |
| * The ref came from a network advertisement and storage is unknown. |
| * <p> |
| * This ref cannot be updated without Git-aware support on the remote |
| * side, as Git-aware code consolidate the remote refs and reported them |
| * to this process. |
| */ |
| NETWORK(false, false); |
| |
| private final boolean loose; |
| |
| private final boolean packed; |
| |
| private Storage(boolean l, boolean p) { |
| loose = l; |
| packed = p; |
| } |
| |
| /** |
| * @return true if this storage has a loose file. |
| */ |
| public boolean isLoose() { |
| return loose; |
| } |
| |
| /** |
| * @return true if this storage is inside the packed file. |
| */ |
| public boolean isPacked() { |
| return packed; |
| } |
| } |
| |
| /** |
| * Update index value when a reference doesn't have one |
| * |
| * @since 5.4 |
| */ |
| long UNDEFINED_UPDATE_INDEX = -1L; |
| |
| /** |
| * What this ref is called within the repository. |
| * |
| * @return name of this ref. |
| */ |
| @NonNull |
| String getName(); |
| |
| /** |
| * Test if this reference is a symbolic reference. |
| * <p> |
| * A symbolic reference does not have its own |
| * {@link org.eclipse.jgit.lib.ObjectId} value, but instead points to |
| * another {@code Ref} in the same database and always uses that other |
| * reference's value as its own. |
| * |
| * @return true if this is a symbolic reference; false if this reference |
| * contains its own ObjectId. |
| */ |
| boolean isSymbolic(); |
| |
| /** |
| * Traverse target references until {@link #isSymbolic()} is false. |
| * <p> |
| * If {@link #isSymbolic()} is false, returns {@code this}. |
| * <p> |
| * If {@link #isSymbolic()} is true, this method recursively traverses |
| * {@link #getTarget()} until {@link #isSymbolic()} returns false. |
| * <p> |
| * This method is effectively |
| * |
| * <pre> |
| * return isSymbolic() ? getTarget().getLeaf() : this; |
| * </pre> |
| * |
| * @return the reference that actually stores the ObjectId value. |
| */ |
| @NonNull |
| Ref getLeaf(); |
| |
| /** |
| * Get the reference this reference points to, or {@code this}. |
| * <p> |
| * If {@link #isSymbolic()} is true this method returns the reference it |
| * directly names, which might not be the leaf reference, but could be |
| * another symbolic reference. |
| * <p> |
| * If this is a leaf level reference that contains its own ObjectId,this |
| * method returns {@code this}. |
| * |
| * @return the target reference, or {@code this}. |
| */ |
| @NonNull |
| Ref getTarget(); |
| |
| /** |
| * Cached value of this ref. |
| * |
| * @return the value of this ref at the last time we read it. May be |
| * {@code null} to indicate a ref that does not exist yet or a |
| * symbolic ref pointing to an unborn branch. |
| */ |
| @Nullable |
| ObjectId getObjectId(); |
| |
| /** |
| * Cached value of <code>ref^{}</code> (the ref peeled to commit). |
| * |
| * @return if this ref is an annotated tag the id of the commit (or tree or |
| * blob) that the annotated tag refers to; {@code null} if this ref |
| * does not refer to an annotated tag. |
| */ |
| @Nullable |
| ObjectId getPeeledObjectId(); |
| |
| /** |
| * Whether the Ref represents a peeled tag. |
| * |
| * @return whether the Ref represents a peeled tag. |
| */ |
| boolean isPeeled(); |
| |
| /** |
| * How was this ref obtained? |
| * <p> |
| * The current storage model of a Ref may influence how the ref must be |
| * updated or deleted from the repository. |
| * |
| * @return type of ref. |
| */ |
| @NonNull |
| Storage getStorage(); |
| |
| /** |
| * Indicator of the relative order between updates of a specific reference |
| * name. A number that increases when a reference is updated. |
| * <p> |
| * With symbolic references, the update index refers to updates of the |
| * symbolic reference itself. For example, if HEAD points to |
| * refs/heads/master, then the update index for exactRef("HEAD") will only |
| * increase when HEAD changes to point to another ref, regardless of how |
| * many times refs/heads/master is updated. |
| * <p> |
| * Should not be used unless the {@code RefDatabase} that instantiated the |
| * ref supports versioning (see {@link RefDatabase#hasVersioning()}) |
| * |
| * @return the update index (i.e. version) of this reference. |
| * @throws UnsupportedOperationException |
| * if the creator of the instance (e.g. {@link RefDatabase}) |
| * doesn't support versioning and doesn't override this method |
| * @since 5.3 |
| */ |
| default long getUpdateIndex() { |
| throw new UnsupportedOperationException(); |
| } |
| } |