1
0
Fork 0
mirror of https://github.com/git/git.git synced 2024-10-31 06:17:56 +01:00
git/Documentation/git-symbolic-ref.txt
Jeff King 48bb914ed6 doc: drop author/documentation sections from most pages
The point of these sections is generally to:

  1. Give credit where it is due.

  2. Give the reader an idea of where to ask questions or
     file bug reports.

But they don't do a good job of either case. For (1), they
are out of date and incomplete. A much more accurate answer
can be gotten through shortlog or blame.  For (2), the
correct contact point is generally git@vger, and even if you
wanted to cc the contact point, the out-of-date and
incomplete fields mean you're likely sending to somebody
useless.

So let's drop the fields entirely from all manpages except
git(1) itself. We already point people to the mailing list
for bug reports there, and we can update the Authors section
to give credit to the major contributors and point to
shortlog and blame for more information.

Each page has a "This is part of git" footer, so people can
follow that to the main git manpage.
2011-03-11 10:59:16 -05:00

58 lines
1.8 KiB
Text

git-symbolic-ref(1)
===================
NAME
----
git-symbolic-ref - Read and modify symbolic refs
SYNOPSIS
--------
'git symbolic-ref' [-q] [-m <reason>] <name> [<ref>]
DESCRIPTION
-----------
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.
Given two arguments, creates or updates a symbolic ref <name> to
point at the given branch <ref>.
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`.
OPTIONS
-------
-q::
--quiet::
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.
-m::
Update the reflog for <name> with <reason>. This is valid only
when creating or updating a symbolic ref.
NOTES
-----
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`.
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 `readlink(1)` command, this was a bit
cumbersome. On some platforms, `ln -sf` does not even work as
advertised (horrors). Therefore symbolic links are now deprecated
and symbolic refs are used by default.
'git symbolic-ref' 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.
GIT
---
Part of the linkgit:git[1] suite