git-symbolic-ref.1   [plain text]

'\" t
.\"     Title: git-symbolic-ref
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 08/19/2012
.\"    Manual: Git Manual
.\"    Source: Git 1.7.12
.\"  Language: English
.\"
.TH "GIT\-SYMBOLIC\-REF" "1" "08/19/2012" "Git 1\&.7\&.12" "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 and modify symbolic refs
.SH "SYNOPSIS"
.sp
.nf
\fIgit symbolic\-ref\fR [\-m <reason>] <name> <ref>
\fIgit symbolic\-ref\fR [\-q] [\-\-short] <name>
.fi
.sp
.SH "DESCRIPTION"
.sp
Given one argument, reads which branch head the given symbolic ref refers to and outputs its path, relative to the \&.git/ directory\&. Typically you would give HEAD 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
A symbolic ref is a regular file that stores a string that begins with ref: refs/\&. For example, your \&.git/HEAD is a regular file whose contents is ref: refs/heads/master\&.
.SH "OPTIONS"
.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
refs/heads/master
to
master\&.
.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, \&.git/HEAD was a symbolic link pointing at refs/heads/master\&. When we wanted to switch to another branch, we did ln \-sf refs/heads/newbranch \&.git/HEAD, and when we wanted to find out which branch we are on, we did readlink \&.git/HEAD\&. 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 "GIT"
.sp
Part of the \fBgit\fR(1) suite