RefUpdate.java
- /*
- * Copyright (C) 2008-2010, Google Inc.
- * Copyright (C) 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 java.io.IOException;
- import java.text.MessageFormat;
- import org.eclipse.jgit.errors.MissingObjectException;
- import org.eclipse.jgit.internal.JGitText;
- import org.eclipse.jgit.revwalk.RevCommit;
- import org.eclipse.jgit.revwalk.RevObject;
- import org.eclipse.jgit.revwalk.RevWalk;
- import org.eclipse.jgit.transport.PushCertificate;
- import org.eclipse.jgit.util.References;
- /**
- * Creates, updates or deletes any reference.
- */
- public abstract class RefUpdate {
- /**
- * Status of an update request.
- * <p>
- * New values may be added to this enum in the future. Callers may assume that
- * unknown values are failures, and may generally treat them the same as
- * {@link #REJECTED_OTHER_REASON}.
- */
- public enum Result {
- /** The ref update/delete has not been attempted by the caller. */
- NOT_ATTEMPTED,
- /**
- * The ref could not be locked for update/delete.
- * <p>
- * This is generally a transient failure and is usually caused by
- * another process trying to access the ref at the same time as this
- * process was trying to update it. It is possible a future operation
- * will be successful.
- */
- LOCK_FAILURE,
- /**
- * Same value already stored.
- * <p>
- * Both the old value and the new value are identical. No change was
- * necessary for an update. For delete the branch is removed.
- */
- NO_CHANGE,
- /**
- * The ref was created locally for an update, but ignored for delete.
- * <p>
- * The ref did not exist when the update started, but it was created
- * successfully with the new value.
- */
- NEW,
- /**
- * The ref had to be forcefully updated/deleted.
- * <p>
- * The ref already existed but its old value was not fully merged into
- * the new value. The configuration permitted a forced update to take
- * place, so ref now contains the new value. History associated with the
- * objects not merged may no longer be reachable.
- */
- FORCED,
- /**
- * The ref was updated/deleted in a fast-forward way.
- * <p>
- * The tracking ref already existed and its old value was fully merged
- * into the new value. No history was made unreachable.
- */
- FAST_FORWARD,
- /**
- * Not a fast-forward and not stored.
- * <p>
- * The tracking ref already existed but its old value was not fully
- * merged into the new value. The configuration did not allow a forced
- * update/delete to take place, so ref still contains the old value. No
- * previous history was lost.
- * <p>
- * <em>Note:</em> Despite the general name, this result only refers to the
- * non-fast-forward case. For more general errors, see {@link
- * #REJECTED_OTHER_REASON}.
- */
- REJECTED,
- /**
- * Rejected because trying to delete the current branch.
- * <p>
- * Has no meaning for update.
- */
- REJECTED_CURRENT_BRANCH,
- /**
- * The ref was probably not updated/deleted because of I/O error.
- * <p>
- * Unexpected I/O error occurred when writing new ref. Such error may
- * result in uncertain state, but most probably ref was not updated.
- * <p>
- * This kind of error doesn't include {@link #LOCK_FAILURE}, which is a
- * different case.
- */
- IO_FAILURE,
- /**
- * The ref was renamed from another name
- * <p>
- */
- RENAMED,
- /**
- * One or more objects aren't in the repository.
- * <p>
- * This is severe indication of either repository corruption on the
- * server side, or a bug in the client wherein the client did not supply
- * all required objects during the pack transfer.
- *
- * @since 4.9
- */
- REJECTED_MISSING_OBJECT,
- /**
- * Rejected for some other reason not covered by another enum value.
- *
- * @since 4.9
- */
- REJECTED_OTHER_REASON;
- }
- /** New value the caller wants this ref to have. */
- private ObjectId newValue;
- /** Does this specification ask for forced updated (rewind/reset)? */
- private boolean force;
- /** Identity to record action as within the reflog. */
- private PersonIdent refLogIdent;
- /** Message the caller wants included in the reflog. */
- private String refLogMessage;
- /** Should the Result value be appended to {@link #refLogMessage}. */
- private boolean refLogIncludeResult;
- /**
- * Should reflogs be written even if the configured default for this ref is
- * not to write it.
- */
- private boolean forceRefLog;
- /** Old value of the ref, obtained after we lock it. */
- private ObjectId oldValue;
- /** If non-null, the value {@link #oldValue} must have to continue. */
- private ObjectId expValue;
- /** Result of the update operation. */
- private Result result = Result.NOT_ATTEMPTED;
- /** Push certificate associated with this update. */
- private PushCertificate pushCert;
- private final Ref ref;
- /**
- * Is this RefUpdate detaching a symbolic ref?
- *
- * We need this info since this.ref will normally be peeled of in case of
- * detaching a symbolic ref (HEAD for example).
- *
- * Without this flag we cannot decide whether the ref has to be updated or
- * not in case when it was a symbolic ref and the newValue == oldValue.
- */
- private boolean detachingSymbolicRef;
- private boolean checkConflicting = true;
- /**
- * Construct a new update operation for the reference.
- * <p>
- * {@code ref.getObjectId()} will be used to seed {@link #getOldObjectId()},
- * which callers can use as part of their own update logic.
- *
- * @param ref
- * the reference that will be updated by this operation.
- */
- protected RefUpdate(Ref ref) {
- this.ref = ref;
- oldValue = ref.getObjectId();
- refLogMessage = ""; //$NON-NLS-1$
- }
- /**
- * Get the reference database this update modifies.
- *
- * @return the reference database this update modifies.
- */
- protected abstract RefDatabase getRefDatabase();
- /**
- * Get the repository storing the database's objects.
- *
- * @return the repository storing the database's objects.
- */
- protected abstract Repository getRepository();
- /**
- * Try to acquire the lock on the reference.
- * <p>
- * If the locking was successful the implementor must set the current
- * identity value by calling {@link #setOldObjectId(ObjectId)}.
- *
- * @param deref
- * true if the lock should be taken against the leaf level
- * reference; false if it should be taken exactly against the
- * current reference.
- * @return true if the lock was acquired and the reference is likely
- * protected from concurrent modification; false if it failed.
- * @throws java.io.IOException
- * the lock couldn't be taken due to an unexpected storage
- * failure, and not because of a concurrent update.
- */
- protected abstract boolean tryLock(boolean deref) throws IOException;
- /**
- * Releases the lock taken by {@link #tryLock} if it succeeded.
- */
- protected abstract void unlock();
- /**
- * Do update
- *
- * @param desiredResult
- * a {@link org.eclipse.jgit.lib.RefUpdate.Result} object.
- * @return {@code result}
- * @throws java.io.IOException
- */
- protected abstract Result doUpdate(Result desiredResult) throws IOException;
- /**
- * Do delete
- *
- * @param desiredResult
- * a {@link org.eclipse.jgit.lib.RefUpdate.Result} object.
- * @return {@code result}
- * @throws java.io.IOException
- */
- protected abstract Result doDelete(Result desiredResult) throws IOException;
- /**
- * Do link
- *
- * @param target
- * a {@link java.lang.String} object.
- * @return {@link org.eclipse.jgit.lib.RefUpdate.Result#NEW} on success.
- * @throws java.io.IOException
- */
- protected abstract Result doLink(String target) throws IOException;
- /**
- * Get the name of the ref this update will operate on.
- *
- * @return name of underlying ref.
- */
- public String getName() {
- return getRef().getName();
- }
- /**
- * Get the reference this update will create or modify.
- *
- * @return the reference this update will create or modify.
- */
- public Ref getRef() {
- return ref;
- }
- /**
- * Get the new value the ref will be (or was) updated to.
- *
- * @return new value. Null if the caller has not configured it.
- */
- public ObjectId getNewObjectId() {
- return newValue;
- }
- /**
- * Tells this RefUpdate that it is actually detaching a symbolic ref.
- */
- public void setDetachingSymbolicRef() {
- detachingSymbolicRef = true;
- }
- /**
- * Return whether this update is actually detaching a symbolic ref.
- *
- * @return true if detaching a symref.
- * @since 4.9
- */
- public boolean isDetachingSymbolicRef() {
- return detachingSymbolicRef;
- }
- /**
- * Set the new value the ref will update to.
- *
- * @param id
- * the new value.
- */
- public void setNewObjectId(AnyObjectId id) {
- newValue = id.copy();
- }
- /**
- * Get the expected value of the ref after the lock is taken, but before
- * update occurs.
- *
- * @return the expected value of the ref after the lock is taken, but before
- * update occurs. Null to avoid the compare and swap test. Use
- * {@link org.eclipse.jgit.lib.ObjectId#zeroId()} to indicate
- * expectation of a non-existant ref.
- */
- public ObjectId getExpectedOldObjectId() {
- return expValue;
- }
- /**
- * Set the expected value of the ref after the lock is taken, but before
- * update occurs.
- *
- * @param id
- * the expected value of the ref after the lock is taken, but
- * before update occurs. Null to avoid the compare and swap test.
- * Use {@link org.eclipse.jgit.lib.ObjectId#zeroId()} to indicate
- * expectation of a non-existant ref.
- */
- public void setExpectedOldObjectId(AnyObjectId id) {
- expValue = id != null ? id.toObjectId() : null;
- }
- /**
- * Check if this update wants to forcefully change the ref.
- *
- * @return true if this update should ignore merge tests.
- */
- public boolean isForceUpdate() {
- return force;
- }
- /**
- * Set if this update wants to forcefully change the ref.
- *
- * @param b
- * true if this update should ignore merge tests.
- */
- public void setForceUpdate(boolean b) {
- force = b;
- }
- /**
- * Get identity of the user making the change in the reflog.
- *
- * @return identity of the user making the change in the reflog.
- */
- public PersonIdent getRefLogIdent() {
- return refLogIdent;
- }
- /**
- * Set the identity of the user appearing in the reflog.
- * <p>
- * The timestamp portion of the identity is ignored. A new identity with the
- * current timestamp will be created automatically when the update occurs
- * and the log record is written.
- *
- * @param pi
- * identity of the user. If null the identity will be
- * automatically determined based on the repository
- * configuration.
- */
- public void setRefLogIdent(PersonIdent pi) {
- refLogIdent = pi;
- }
- /**
- * Get the message to include in the reflog.
- *
- * @return message the caller wants to include in the reflog; null if the
- * update should not be logged.
- */
- public String getRefLogMessage() {
- return refLogMessage;
- }
- /**
- * Whether the ref log message should show the result.
- *
- * @return {@code true} if the ref log message should show the result.
- */
- protected boolean isRefLogIncludingResult() {
- return refLogIncludeResult;
- }
- /**
- * Set the message to include in the reflog.
- * <p>
- * Repository implementations may limit which reflogs are written by default,
- * based on the project configuration. If a repo is not configured to write
- * logs for this ref by default, setting the message alone may have no effect.
- * To indicate that the repo should write logs for this update in spite of
- * configured defaults, use {@link #setForceRefLog(boolean)}.
- *
- * @param msg
- * the message to describe this change. It may be null if
- * appendStatus is null in order not to append to the reflog
- * @param appendStatus
- * true if the status of the ref change (fast-forward or
- * forced-update) should be appended to the user supplied
- * message.
- */
- public void setRefLogMessage(String msg, boolean appendStatus) {
- if (msg == null && !appendStatus)
- disableRefLog();
- else if (msg == null && appendStatus) {
- refLogMessage = ""; //$NON-NLS-1$
- refLogIncludeResult = true;
- } else {
- refLogMessage = msg;
- refLogIncludeResult = appendStatus;
- }
- }
- /**
- * Don't record this update in the ref's associated reflog.
- */
- public void disableRefLog() {
- refLogMessage = null;
- refLogIncludeResult = false;
- }
- /**
- * Force writing a reflog for the updated ref.
- *
- * @param force whether to force.
- * @since 4.9
- */
- public void setForceRefLog(boolean force) {
- forceRefLog = force;
- }
- /**
- * Check whether the reflog should be written regardless of repo defaults.
- *
- * @return whether force writing is enabled.
- * @since 4.9
- */
- protected boolean isForceRefLog() {
- return forceRefLog;
- }
- /**
- * The old value of the ref, prior to the update being attempted.
- * <p>
- * This value may differ before and after the update method. Initially it is
- * populated with the value of the ref before the lock is taken, but the old
- * value may change if someone else modified the ref between the time we
- * last read it and when the ref was locked for update.
- *
- * @return the value of the ref prior to the update being attempted; null if
- * the updated has not been attempted yet.
- */
- public ObjectId getOldObjectId() {
- return oldValue;
- }
- /**
- * Set the old value of the ref.
- *
- * @param old
- * the old value.
- */
- protected void setOldObjectId(ObjectId old) {
- oldValue = old;
- }
- /**
- * Set a push certificate associated with this update.
- * <p>
- * This usually includes a command to update this ref, but is not required to.
- *
- * @param cert
- * push certificate, may be null.
- * @since 4.1
- */
- public void setPushCertificate(PushCertificate cert) {
- pushCert = cert;
- }
- /**
- * Set the push certificate associated with this update.
- * <p>
- * This usually includes a command to update this ref, but is not required to.
- *
- * @return push certificate, may be null.
- * @since 4.1
- */
- protected PushCertificate getPushCertificate() {
- return pushCert;
- }
- /**
- * Get the status of this update.
- * <p>
- * The same value that was previously returned from an update method.
- *
- * @return the status of the update.
- */
- public Result getResult() {
- return result;
- }
- private void requireCanDoUpdate() {
- if (newValue == null)
- throw new IllegalStateException(JGitText.get().aNewObjectIdIsRequired);
- }
- /**
- * Force the ref to take the new value.
- * <p>
- * This is just a convenient helper for setting the force flag, and as such
- * the merge test is performed.
- *
- * @return the result status of the update.
- * @throws java.io.IOException
- * an unexpected IO error occurred while writing changes.
- */
- public Result forceUpdate() throws IOException {
- force = true;
- return update();
- }
- /**
- * Gracefully update the ref to the new value.
- * <p>
- * Merge test will be performed according to {@link #isForceUpdate()}.
- * <p>
- * This is the same as:
- *
- * <pre>
- * return update(new RevWalk(getRepository()));
- * </pre>
- *
- * @return the result status of the update.
- * @throws java.io.IOException
- * an unexpected IO error occurred while writing changes.
- */
- public Result update() throws IOException {
- try (RevWalk rw = new RevWalk(getRepository())) {
- rw.setRetainBody(false);
- return update(rw);
- }
- }
- /**
- * Gracefully update the ref to the new value.
- * <p>
- * Merge test will be performed according to {@link #isForceUpdate()}.
- *
- * @param walk
- * a RevWalk instance this update command can borrow to perform
- * the merge test. The walk will be reset to perform the test.
- * @return the result status of the update.
- * @throws java.io.IOException
- * an unexpected IO error occurred while writing changes.
- */
- public Result update(RevWalk walk) throws IOException {
- requireCanDoUpdate();
- try {
- return result = updateImpl(walk, new Store() {
- @Override
- Result execute(Result status) throws IOException {
- if (status == Result.NO_CHANGE)
- return status;
- return doUpdate(status);
- }
- });
- } catch (IOException x) {
- result = Result.IO_FAILURE;
- throw x;
- }
- }
- /**
- * Delete the ref.
- * <p>
- * This is the same as:
- *
- * <pre>
- * return delete(new RevWalk(getRepository()));
- * </pre>
- *
- * @return the result status of the delete.
- * @throws java.io.IOException
- */
- public Result delete() throws IOException {
- try (RevWalk rw = new RevWalk(getRepository())) {
- rw.setRetainBody(false);
- return delete(rw);
- }
- }
- /**
- * Delete the ref.
- *
- * @param walk
- * a RevWalk instance this delete command can borrow to perform
- * the merge test. The walk will be reset to perform the test.
- * @return the result status of the delete.
- * @throws java.io.IOException
- */
- public Result delete(RevWalk walk) throws IOException {
- final String myName = detachingSymbolicRef
- ? getRef().getName()
- : getRef().getLeaf().getName();
- if (myName.startsWith(Constants.R_HEADS) && !getRepository().isBare()) {
- // Don't allow the currently checked out branch to be deleted.
- Ref head = getRefDatabase().exactRef(Constants.HEAD);
- while (head != null && head.isSymbolic()) {
- head = head.getTarget();
- if (myName.equals(head.getName()))
- return result = Result.REJECTED_CURRENT_BRANCH;
- }
- }
- try {
- return result = updateImpl(walk, new Store() {
- @Override
- Result execute(Result status) throws IOException {
- return doDelete(status);
- }
- });
- } catch (IOException x) {
- result = Result.IO_FAILURE;
- throw x;
- }
- }
- /**
- * Replace this reference with a symbolic reference to another reference.
- * <p>
- * This exact reference (not its traversed leaf) is replaced with a symbolic
- * reference to the requested name.
- *
- * @param target
- * name of the new target for this reference. The new target name
- * must be absolute, so it must begin with {@code refs/}.
- * @return {@link org.eclipse.jgit.lib.RefUpdate.Result#NEW} or
- * {@link org.eclipse.jgit.lib.RefUpdate.Result#FORCED} on success.
- * @throws java.io.IOException
- */
- public Result link(String target) throws IOException {
- if (!target.startsWith(Constants.R_REFS))
- throw new IllegalArgumentException(MessageFormat.format(JGitText.get().illegalArgumentNotA, Constants.R_REFS));
- if (checkConflicting && getRefDatabase().isNameConflicting(getName()))
- return Result.LOCK_FAILURE;
- try {
- if (!tryLock(false))
- return Result.LOCK_FAILURE;
- final Ref old = getRefDatabase().exactRef(getName());
- if (old != null && old.isSymbolic()) {
- final Ref dst = old.getTarget();
- if (target.equals(dst.getName()))
- return result = Result.NO_CHANGE;
- }
- if (old != null && old.getObjectId() != null)
- setOldObjectId(old.getObjectId());
- final Ref dst = getRefDatabase().exactRef(target);
- if (dst != null && dst.getObjectId() != null)
- setNewObjectId(dst.getObjectId());
- return result = doLink(target);
- } catch (IOException x) {
- result = Result.IO_FAILURE;
- throw x;
- } finally {
- unlock();
- }
- }
- private Result updateImpl(RevWalk walk, Store store)
- throws IOException {
- RevObject newObj;
- RevObject oldObj;
- // don't make expensive conflict check if this is an existing Ref
- if (oldValue == null && checkConflicting
- && getRefDatabase().isNameConflicting(getName())) {
- return Result.LOCK_FAILURE;
- }
- try {
- // If we're detaching a symbolic reference, we should update the reference
- // itself. Otherwise, we will update the leaf reference, which should be
- // an ObjectIdRef.
- if (!tryLock(!detachingSymbolicRef)) {
- return Result.LOCK_FAILURE;
- }
- if (expValue != null) {
- final ObjectId o;
- o = oldValue != null ? oldValue : ObjectId.zeroId();
- if (!AnyObjectId.isEqual(expValue, o)) {
- return Result.LOCK_FAILURE;
- }
- }
- try {
- newObj = safeParseNew(walk, newValue);
- } catch (MissingObjectException e) {
- return Result.REJECTED_MISSING_OBJECT;
- }
- if (oldValue == null) {
- return store.execute(Result.NEW);
- }
- oldObj = safeParseOld(walk, oldValue);
- if (References.isSameObject(newObj, oldObj)
- && !detachingSymbolicRef) {
- return store.execute(Result.NO_CHANGE);
- }
- if (isForceUpdate()) {
- return store.execute(Result.FORCED);
- }
- if (newObj instanceof RevCommit && oldObj instanceof RevCommit) {
- if (walk.isMergedInto((RevCommit) oldObj, (RevCommit) newObj)) {
- return store.execute(Result.FAST_FORWARD);
- }
- }
- return Result.REJECTED;
- } finally {
- unlock();
- }
- }
- /**
- * Enable/disable the check for conflicting ref names. By default conflicts
- * are checked explicitly.
- *
- * @param check
- * whether to enable the check for conflicting ref names.
- * @since 3.0
- */
- public void setCheckConflicting(boolean check) {
- checkConflicting = check;
- }
- private static RevObject safeParseNew(RevWalk rw, AnyObjectId newId)
- throws IOException {
- if (newId == null || ObjectId.zeroId().equals(newId)) {
- return null;
- }
- return rw.parseAny(newId);
- }
- private static RevObject safeParseOld(RevWalk rw, AnyObjectId oldId)
- throws IOException {
- try {
- return oldId != null ? rw.parseAny(oldId) : null;
- } catch (MissingObjectException e) {
- // We can expect some old objects to be missing, like if we are trying to
- // force a deletion of a branch and the object it points to has been
- // pruned from the database due to freak corruption accidents (it happens
- // with 'git new-work-dir').
- return null;
- }
- }
- /**
- * Handle the abstraction of storing a ref update. This is because both
- * updating and deleting of a ref have merge testing in common.
- */
- private abstract static class Store {
- abstract Result execute(Result status) throws IOException;
- }
- }