mirror of
https://github.com/git/git
synced 2024-08-25 02:35:46 +00:00
Add missing documentation.
Signed-off-by: Junio C Hamano <junkio@cox.net>
This commit is contained in:
parent
b10c1a74f0
commit
129056370a
52
Documentation/git-symbolic-ref.txt
Normal file
52
Documentation/git-symbolic-ref.txt
Normal file
|
@ -0,0 +1,52 @@
|
|||
git-symbolic-ref(1)
|
||||
===================
|
||||
|
||||
NAME
|
||||
----
|
||||
git-symbolic-ref - read and modify symbolic refs
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
'git-symbolic-ref' <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 on which branch your working tree is on.
|
||||
|
||||
Give two arguments, create or update a symbolic ref <name> to
|
||||
point at the given branch <ref>.
|
||||
|
||||
Traditionally, `.git/HEAD` is a symlink pointing at
|
||||
`refs/heads/master`. When we want to switch to another branch,
|
||||
we did `ln -sf refs/heads/newbranch .git/HEAD`, and when we want
|
||||
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 does not have working symlinks,
|
||||
or that does not have the `readlink(1)` command, this was a bit
|
||||
cumbersome. On some platforms, `ln -sf` does not even work as
|
||||
advertised (horrors).
|
||||
|
||||
A symbolic ref can be a regular file that stores a string that
|
||||
begins with `ref: refs/`. For example, your `.git/HEAD` *can*
|
||||
be a regular file whose contents is `ref: refs/heads/master`.
|
||||
This can be used on a filesystem that does not support symbolic
|
||||
links. Instead of doing `readlink .git/HEAD`, `git-symbolic-ref
|
||||
HEAD` can be used to find out which branch we are on. To point
|
||||
the HEAD to `newbranch`, instead of `ln -sf refs/heads/newbranch
|
||||
.git/HEAD`, `git-symbolic-ref HEAD refs/heads/newbranch` can be
|
||||
used.
|
||||
|
||||
Currently, .git/HEAD uses a regular file symbolic ref on Cygwin,
|
||||
and everywhere else it is implemented as a symlink. This can be
|
||||
changed at compilation time.
|
||||
|
||||
Author
|
||||
------
|
||||
Written by Junio C Hamano <junkio@cox.net>
|
||||
|
||||
GIT
|
||||
---
|
||||
Part of the gitlink:git[7] suite
|
58
Documentation/git-update-ref.txt
Normal file
58
Documentation/git-update-ref.txt
Normal file
|
@ -0,0 +1,58 @@
|
|||
git-update-ref(1)
|
||||
=================
|
||||
|
||||
NAME
|
||||
----
|
||||
git-update-ref - update the object name stored in a ref safely
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
`git-update-ref` <ref> <newvalue> [<oldvalue>]
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
Given two arguments, stores the <newvalue> in the <ref>, possibly
|
||||
dereferencing the symbolic refs. E.g. `git-update-ref HEAD
|
||||
<newvalue>` updates the current branch head to the new object.
|
||||
|
||||
Given three arguments, stores the <newvalue> in the <ref>,
|
||||
possibly dereferencing the symbolic refs, after verifying that
|
||||
the current value of the <ref> matches <oldvalue>.
|
||||
E.g. `git-update-ref refs/heads/master <newvalue> <oldvalue>`
|
||||
updates the master branch head to <newvalue> only if its current
|
||||
value is <oldvalue>.
|
||||
|
||||
It also allows a "ref" file to be a symbolic pointer to another
|
||||
ref file by starting with the four-byte header sequence of
|
||||
"ref:".
|
||||
|
||||
More importantly, it allows the update of a ref file to follow
|
||||
these symbolic pointers, whether they are symlinks or these
|
||||
"regular file symbolic refs". It follows *real* symlinks only
|
||||
if they start with "refs/": otherwise it will just try to read
|
||||
them and update them as a regular file (i.e. it will allow the
|
||||
filesystem to follow them, but will overwrite such a symlink to
|
||||
somewhere else with a regular filename).
|
||||
|
||||
In general, using
|
||||
|
||||
git-update-ref HEAD "$head"
|
||||
|
||||
should be a _lot_ safer than doing
|
||||
|
||||
echo "$head" > "$GIT_DIR/HEAD"
|
||||
|
||||
both from a symlink following standpoint *and* an error checking
|
||||
standpoint. The "refs/" rule for symlinks means that symlinks
|
||||
that point to "outside" the tree are safe: they'll be followed
|
||||
for reading but not for writing (so we'll never write through a
|
||||
ref symlink to some other tree, if you have copied a whole
|
||||
archive by creating a symlink tree).
|
||||
|
||||
Author
|
||||
------
|
||||
Written by Linus Torvalds <torvalds@osdl.org>.
|
||||
|
||||
GIT
|
||||
---
|
||||
Part of the gitlink:git[7] suite
|
Loading…
Reference in a new issue