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