@matheusbsbs / matheus-bagliano / commits / 129056370a
Fork 0

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