<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect2 SYSTEM "../../../dtd/dblite.dtd">

<sect2 lang="en" id="git-symbolic-ref(1)">
    <title>git-symbolic-ref(1)</title>
    <date>2024-07-02</date>
<revhistory><revision><date>2024-07-02</date></revision></revhistory>
<indexterm>
<primary>git-symbolic-ref(1)</primary>
</indexterm>
<simplesect id="git-symbolic-ref(1)__name">
<title>NAME</title>
<simpara>git-symbolic-ref - Read, modify and delete symbolic refs</simpara>
</simplesect>
<simplesect id="git-symbolic-ref(1)__synopsis">
<title>SYNOPSIS</title>
<blockquote>
<literallayout><emphasis>git symbolic-ref</emphasis> [-m &lt;reason&gt;] &lt;name&gt; &lt;ref&gt;
<emphasis>git symbolic-ref</emphasis> [-q] [--short] [--no-recurse] &lt;name&gt;
<emphasis>git symbolic-ref</emphasis> --delete [-q] &lt;name&gt;</literallayout>
</blockquote>
</simplesect>
<simplesect id="git-symbolic-ref(1)__description">
<title>DESCRIPTION</title>
<simpara>Given one argument, reads which branch head the given symbolic
ref refers to and outputs its path, relative to the <emphasis>.git/</emphasis>
directory.  Typically you would give <emphasis>HEAD</emphasis> as the &lt;name&gt;
argument to see which branch your working tree is on.</simpara>
<simpara>Given two arguments, creates or updates a symbolic ref &lt;name&gt; to
point at the given branch &lt;ref&gt;.</simpara>
<simpara>Given <emphasis>--delete</emphasis> and an additional argument, deletes the given
symbolic ref.</simpara>
<simpara>A symbolic ref is a regular file that stores a string that
begins with <emphasis>ref: refs/</emphasis>.  For example, your <emphasis>.git/HEAD</emphasis> is
a regular file whose content is <emphasis>ref: refs/heads/master</emphasis>.</simpara>
</simplesect>
<simplesect id="git-symbolic-ref(1)__options">
<title>OPTIONS</title>
<variablelist>
<varlistentry>
<term>
-d
</term>
<term>
--delete
</term>
<listitem>
<simpara>
        Delete the symbolic ref &lt;name&gt;.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-q
</term>
<term>
--quiet
</term>
<listitem>
<simpara>
        Do not issue an error message if the &lt;name&gt; is not a
        symbolic ref but a detached HEAD; instead exit with
        non-zero status silently.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--short
</term>
<listitem>
<simpara>
        When showing the value of &lt;name&gt; as a symbolic ref, try to shorten the
        value, e.g. from <emphasis>refs/heads/master</emphasis> to <emphasis>master</emphasis>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--recurse
</term>
<term>
--no-recurse
</term>
<listitem>
<simpara>
        When showing the value of &lt;name&gt; as a symbolic ref, if
        &lt;name&gt; refers to another symbolic ref, follow such a chain
        of symbolic refs until the result no longer points at a
        symbolic ref (<emphasis>--recurse</emphasis>, which is the default).
        <emphasis>--no-recurse</emphasis> stops after dereferencing only a single level
        of symbolic ref.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-m
</term>
<listitem>
<simpara>
        Update the reflog for &lt;name&gt; with &lt;reason&gt;.  This is valid only
        when creating or updating a symbolic ref.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</simplesect>
<simplesect id="git-symbolic-ref(1)__notes">
<title>NOTES</title>
<simpara>In the past, <emphasis>.git/HEAD</emphasis> was a symbolic link pointing at
<emphasis>refs/heads/master</emphasis>.  When we wanted to switch to another branch,
we did <emphasis>ln -sf refs/heads/newbranch .git/HEAD</emphasis>, and when we wanted
to find out which branch we are on, we did <emphasis>readlink .git/HEAD</emphasis>.
But symbolic links are not entirely portable, so they are now
deprecated and symbolic refs (as described above) are used by
default.</simpara>
<simpara><emphasis>git symbolic-ref</emphasis> 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.</simpara>
</simplesect>
<simplesect id="git-symbolic-ref(1)__git">
<title>GIT</title>
<simpara>Part of the <xref linkend="git(1)" /> suite</simpara>
</simplesect>
</sect2>
