Merge http://www.kernel.org/pub/scm/gitk/gitk
[git/git.git] / Documentation / git-symbolic-ref.txt
1 git-symbolic-ref(1)
2 ===================
3
4 NAME
5 ----
6 git-symbolic-ref - read and modify symbolic refs
7
8 SYNOPSIS
9 --------
10 'git-symbolic-ref' <name> [<ref>]
11
12 DESCRIPTION
13 -----------
14 Given one argument, reads which branch head the given symbolic
15 ref refers to and outputs its path, relative to the `.git/`
16 directory. Typically you would give `HEAD` as the <name>
17 argument to see on which branch your working tree is on.
18
19 Give two arguments, create or update a symbolic ref <name> to
20 point at the given branch <ref>.
21
22 Traditionally, `.git/HEAD` is a symlink pointing at
23 `refs/heads/master`. When we want to switch to another branch,
24 we did `ln -sf refs/heads/newbranch .git/HEAD`, and when we want
25 to find out which branch we are on, we did `readlink .git/HEAD`.
26 This was fine, and internally that is what still happens by
27 default, but on platforms that does not have working symlinks,
28 or that does not have the `readlink(1)` command, this was a bit
29 cumbersome. On some platforms, `ln -sf` does not even work as
30 advertised (horrors).
31
32 A symbolic ref can be a regular file that stores a string that
33 begins with `ref: refs/`. For example, your `.git/HEAD` *can*
34 be a regular file whose contents is `ref: refs/heads/master`.
35 This can be used on a filesystem that does not support symbolic
36 links. Instead of doing `readlink .git/HEAD`, `git-symbolic-ref
37 HEAD` can be used to find out which branch we are on. To point
38 the HEAD to `newbranch`, instead of `ln -sf refs/heads/newbranch
39 .git/HEAD`, `git-symbolic-ref HEAD refs/heads/newbranch` can be
40 used.
41
42 Currently, .git/HEAD uses a regular file symbolic ref on Cygwin,
43 and everywhere else it is implemented as a symlink. This can be
44 changed at compilation time.
45
46 Author
47 ------
48 Written by Junio C Hamano <junkio@cox.net>
49
50 GIT
51 ---
52 Part of the gitlink:git[7] suite