git-update-ref

Delete a ref, useful for soft resetting the first commit

$ git update-ref -d [HEAD]

$ git update-ref -m [message] [HEAD] [4e95e05]

git update-ref [-m <reason>] (-d | --delete) <ref> [<oldvalue>]
git update-ref [-m <reason>] [--no-deref] <ref> <newvalue> [<oldvalue>]
git update-ref [-m <reason>] [--no-deref] [--single-reflog] [--create-reflog] --stdin
git update-ref [--atomic] [--stdin]

ref
    The name of the ref to update. For example, HEAD or refs/heads/main.

newvalue
    The new object name (SHA-1 or SHA-256 hash) or ref name that <ref> should point to.

oldvalue
    The expected current value of <ref>. If provided, the update will only occur if <ref> currently points to <oldvalue>, ensuring a compare-and-swap behavior.

-d, --delete
    Delete the specified ref.

-m
    Update the reflog for <ref> with a message indicating the reason for the update.

--no-deref
    Update a symbolic ref directly instead of updating the ref it points to.

--create-reflog
    Create a reflog for the ref, even if it's not normally logged (e.g., tags).

--single-reflog
    This flag is a no-op, kept for historical reasons.

--stdin
    Read ref updates from standard input in the format: oldvalue newvalue ref. Allows for atomic batch updates.

--atomic
    When used with --stdin, ensures that all updates succeed or all fail as a single atomic transaction.

--abort-if-ungrouped
    Used with --stdin, aborts the operation if any line from stdin is not part of a group (i.e., not preceded by start_group and followed by end_group).

git-update-ref is a fundamental Git plumbing command used to safely and atomically update the object name or symbolic reference stored in a ref. Refs are typically files located in the .git/refs/ directory (e.g., .git/refs/heads/main for the main branch). This command ensures that updates are performed reliably, preventing race conditions and data corruption, especially in environments with concurrent operations. It allows users to update a ref to a newvalue, optionally checking against an oldvalue for a compare-and-swap operation. It can also be used to delete a ref or create a new one. The command records updates in the reflog, providing a history of changes to the ref, which is crucial for operations like git reflog. For advanced use cases, it supports reading multiple update instructions from standard input, enabling efficient bulk operations.

Directly manipulating ref files in the .git/refs/ directory is highly discouraged. Always use git-update-ref to ensure atomic and safe updates, especially when dealing with concurrent operations or symbolic refs. Incorrect manual modifications can lead to repository corruption.

While many high-level Git commands (like git commit, git branch, git reset) automatically update refs as part of their operation, git-update-ref provides a low-level, precise control for managing refs directly. It is a critical "plumbing" command that ensures the integrity of the Git repository's internal structure. Its ability to perform compare-and-swap updates (oldvalue check) is vital for ensuring that updates are applied only if the ref is in an expected state, preventing accidental overwrites due to concurrent changes. The --stdin option further enhances its utility by allowing multiple ref updates to be performed as a single atomic operation, which is crucial for performance and consistency in complex scenarios, such as garbage collection or repository migrations.

git-for-each-ref(1), git-show-ref(1), git-rev-parse(1), git-symbolic-ref(1), git-reflog(1)