man1/git-symbolic-ref.1

'\" t
.\"     Title: git-symbolic-ref
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
.\"      Date: 2025-09-29
.\"    Manual: Git Manual
.\"    Source: Git 2.51.0.372.g821f583da6
.\"  Language: English
.\"
.TH "GIT\-SYMBOLIC\-REF" "1" "2025-09-29" "Git 2\&.51\&.0\&.372\&.g821f58" "Git Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
git-symbolic-ref \- Read, modify and delete symbolic refs
.SH "SYNOPSIS"
.sp
.nf
\fIgit symbolic\-ref\fR [\-m <reason>] <name> <ref>
\fIgit symbolic\-ref\fR [\-q] [\-\-short] [\-\-no\-recurse] <name>
\fIgit symbolic\-ref\fR \-\-delete [\-q] <name>
.fi
.SH "DESCRIPTION"
.sp
Given one argument, reads which branch head the given symbolic ref refers to and outputs its path, relative to the \&.\fBgit/\fR directory\&. Typically you would give \fBHEAD\fR as the <name> argument to see which branch your working tree is on\&.
.sp
Given two arguments, creates or updates a symbolic ref <name> to point at the given branch <ref>\&.
.sp
Given \fB\-\-delete\fR and an additional argument, deletes the given symbolic ref\&.
.sp
A symbolic ref is a regular file that stores a string that begins with \fBref:\fR \fBrefs/\fR\&. For example, your \&.\fBgit/HEAD\fR is a regular file whose content is \fBref:\fR \fBrefs/heads/master\fR\&.
.SH "OPTIONS"
.PP
\-d, \-\-delete
.RS 4
Delete the symbolic ref <name>\&.
.RE
.PP
\-q, \-\-quiet
.RS 4
Do not issue an error message if the <name> is not a symbolic ref but a detached HEAD; instead exit with non\-zero status silently\&.
.RE
.PP
\-\-short
.RS 4
When showing the value of <name> as a symbolic ref, try to shorten the value, e\&.g\&. from
\fBrefs/heads/master\fR
to
\fBmaster\fR\&.
.RE
.PP
\-\-recurse, \-\-no\-recurse
.RS 4
When showing the value of <name> as a symbolic ref, if <name> refers to another symbolic ref, follow such a chain of symbolic refs until the result no longer points at a symbolic ref (\fB\-\-recurse\fR, which is the default)\&.
\fB\-\-no\-recurse\fR
stops after dereferencing only a single level of symbolic ref\&.
.RE
.PP
\-m
.RS 4
Update the reflog for <name> with <reason>\&. This is valid only when creating or updating a symbolic ref\&.
.RE
.SH "NOTES"
.sp
In the past, \&.\fBgit/HEAD\fR was a symbolic link pointing at \fBrefs/heads/master\fR\&. When we wanted to switch to another branch, we did \fBln\fR \fB\-sf\fR \fBrefs/heads/newbranch\fR \fB\&.git/HEAD\fR, and when we wanted to find out which branch we are on, we did \fBreadlink\fR \fB\&.git/HEAD\fR\&. But symbolic links are not entirely portable, so they are now deprecated and symbolic refs (as described above) are used by default\&.
.sp
\fIgit symbolic\-ref\fR will exit with status 0 if the contents of the symbolic ref were printed correctly, with status 1 if the requested name is not a symbolic ref, or 128 if another error occurs\&.
.SH "SEE ALSO"
.sp
\fBgit-update-ref\fR(1)
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite