1 <?xml version="1.0" encoding="UTF-8"?>
\r
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
\r
4 <article lang="en" id="git-symbolic-ref(1)">
\r
6 <title>git-symbolic-ref(1)</title>
\r
8 <primary>git-symbolic-ref(1)</primary>
\r
11 <simplesect id="_name">
\r
13 <simpara>git-symbolic-ref - Read and modify symbolic refs</simpara>
\r
15 <simplesect id="_synopsis">
\r
16 <title>SYNOPSIS</title>
\r
17 <simpara><emphasis>git symbolic-ref</emphasis> [-q] [-m <reason>] <name> [<ref>]</simpara>
\r
19 <simplesect id="_description">
\r
20 <title>DESCRIPTION</title>
\r
21 <simpara>Given one argument, reads which branch head the given symbolic
\r
22 ref refers to and outputs its path, relative to the <literal>.git/</literal>
\r
23 directory. Typically you would give <literal>HEAD</literal> as the <name>
\r
24 argument to see on which branch your working tree is on.</simpara>
\r
25 <simpara>Give two arguments, create or update a symbolic ref <name> to
\r
26 point at the given branch <ref>.</simpara>
\r
27 <simpara>A symbolic ref is a regular file that stores a string that
\r
28 begins with <literal>ref: refs/</literal>. For example, your <literal>.git/HEAD</literal> is
\r
29 a regular file whose contents is <literal>ref: refs/heads/master</literal>.</simpara>
\r
31 <simplesect id="_options">
\r
32 <title>OPTIONS</title>
\r
43 Do not issue an error message if the <name> is not a
\r
44 symbolic ref but a detached HEAD; instead exit with
\r
45 non-zero status silently.
\r
55 Update the reflog for <name> with <reason>. This is valid only
\r
56 when creating or updating a symbolic ref.
\r
62 <simplesect id="_notes">
\r
63 <title>NOTES</title>
\r
64 <simpara>In the past, <literal>.git/HEAD</literal> was a symbolic link pointing at
\r
65 <literal>refs/heads/master</literal>. When we wanted to switch to another branch,
\r
66 we did <literal>ln -sf refs/heads/newbranch .git/HEAD</literal>, and when we wanted
\r
67 to find out which branch we are on, we did <literal>readlink .git/HEAD</literal>.
\r
68 This was fine, and internally that is what still happens by
\r
69 default, but on platforms that do not have working symlinks,
\r
70 or that do not have the <literal>readlink(1)</literal> command, this was a bit
\r
71 cumbersome. On some platforms, <literal>ln -sf</literal> does not even work as
\r
72 advertised (horrors). Therefore symbolic links are now deprecated
\r
73 and symbolic refs are used by default.</simpara>
\r
74 <simpara><emphasis>git-symbolic-ref</emphasis> will exit with status 0 if the contents of the
\r
75 symbolic ref were printed correctly, with status 1 if the requested
\r
76 name is not a symbolic ref, or 128 if another error occurs.</simpara>
\r
78 <simplesect id="_author">
\r
79 <title>Author</title>
\r
80 <simpara>Written by Junio C Hamano <<ulink url="mailto:gitster@pobox.com">gitster@pobox.com</ulink>></simpara>
\r
82 <simplesect id="_git">
\r
84 <simpara>Part of the <xref linkend="git(1)"/> suite</simpara>
\r