<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<article lang="en" id="git-symbolic-ref(1)">
<articleinfo>
    <title>git-symbolic-ref(1)</title>
        <indexterm>
                <primary>git-symbolic-ref(1)</primary>
        </indexterm>
</articleinfo>
<simplesect id="_name">
<title>NAME</title>
<simpara>git-symbolic-ref - Read and modify symbolic refs</simpara>
</simplesect>
<simplesect id="_synopsis">
<title>SYNOPSIS</title>
<simpara><emphasis>git symbolic-ref</emphasis> [-q] [-m &lt;reason&gt;] &lt;name&gt; [&lt;ref&gt;]</simpara>
</simplesect>
<simplesect id="_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 <literal>.git/</literal>
directory.  Typically you would give <literal>HEAD</literal> as the &lt;name&gt;
argument to see on which branch your working tree is on.</simpara>
<simpara>Give two arguments, create or update a symbolic ref &lt;name&gt; to
point at the given branch &lt;ref&gt;.</simpara>
<simpara>A symbolic ref is a regular file that stores a string that
begins with <literal>ref: refs/</literal>.  For example, your <literal>.git/HEAD</literal> is
a regular file whose contents is <literal>ref: refs/heads/master</literal>.</simpara>
</simplesect>
<simplesect id="_options">
<title>OPTIONS</title>
<variablelist>
<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>
-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="_notes">
<title>NOTES</title>
<simpara>In the past, <literal>.git/HEAD</literal> was a symbolic link pointing at
<literal>refs/heads/master</literal>.  When we wanted to switch to another branch,
we did <literal>ln -sf refs/heads/newbranch .git/HEAD</literal>, and when we wanted
to find out which branch we are on, we did <literal>readlink .git/HEAD</literal>.
This was fine, and internally that is what still happens by
default, but on platforms that do not have working symlinks,
or that do not have the <literal>readlink(1)</literal> command, this was a bit
cumbersome.  On some platforms, <literal>ln -sf</literal> does not even work as
advertised (horrors).  Therefore symbolic links are now deprecated
and symbolic refs 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="_author">
<title>Author</title>
<simpara>Written by Junio C Hamano &lt;<ulink url="mailto:gitster@pobox.com">gitster@pobox.com</ulink>&gt;</simpara>
</simplesect>
<simplesect id="_git">
<title>GIT</title>
<simpara>Part of the <xref linkend="git(1)"/> suite</simpara>
</simplesect>
</article>
