Add missing documentation.
Signed-off-by: Junio C Hamano <junkio@cox.net>
Junio C Hamano committed
Oct 4, 2005 at 16:45 UTC
129056370abff1cc0d347b98fe88afc44a6cb8c0
2 files changed
+110
Documentation/git-symbolic-ref.txt
new
+52
@@ -0,0 +1,52 @@
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
Documentation/git-update-ref.txt
new
+58
@@ -0,0 +1,58 @@
1
+git-update-ref(1)
2
+=================
3
+
4
+NAME
5
+----
6
+git-update-ref - update the object name stored in a ref safely
7
+
8
+SYNOPSIS
9
+--------
10
+`git-update-ref` <ref> <newvalue> [<oldvalue>]
11
+
12
+DESCRIPTION
13
+-----------
14
+Given two arguments, stores the <newvalue> in the <ref>, possibly
15
+dereferencing the symbolic refs. E.g. `git-update-ref HEAD
16
+<newvalue>` updates the current branch head to the new object.
17
+
18
+Given three arguments, stores the <newvalue> in the <ref>,
19
+possibly dereferencing the symbolic refs, after verifying that
20
+the current value of the <ref> matches <oldvalue>.
21
+E.g. `git-update-ref refs/heads/master <newvalue> <oldvalue>`
22
+updates the master branch head to <newvalue> only if its current
23
+value is <oldvalue>.
24
+
25
+It also allows a "ref" file to be a symbolic pointer to another
26
+ref file by starting with the four-byte header sequence of
27
+"ref:".
28
+
29
+More importantly, it allows the update of a ref file to follow
30
+these symbolic pointers, whether they are symlinks or these
31
+"regular file symbolic refs". It follows *real* symlinks only
32
+if they start with "refs/": otherwise it will just try to read
33
+them and update them as a regular file (i.e. it will allow the
34
+filesystem to follow them, but will overwrite such a symlink to
35
+somewhere else with a regular filename).
36
+
37
+In general, using
38
+
39
+ git-update-ref HEAD "$head"
40
+
41
+should be a _lot_ safer than doing
42
+
43
+ echo "$head" > "$GIT_DIR/HEAD"
44
+
45
+both from a symlink following standpoint *and* an error checking
46
+standpoint. The "refs/" rule for symlinks means that symlinks
47
+that point to "outside" the tree are safe: they'll be followed
48
+for reading but not for writing (so we'll never write through a
49
+ref symlink to some other tree, if you have copied a whole
50
+archive by creating a symlink tree).
51
+
52
+Author
53
+------
54
+Written by Linus Torvalds <torvalds@osdl.org>.
55
+
56
+GIT
57
+---
58
+Part of the gitlink:git[7] suite