diff options
Diffstat (limited to 'Documentation/git-update-ref.txt')
| -rw-r--r-- | Documentation/git-update-ref.txt | 58 |
1 files changed, 58 insertions, 0 deletions
diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt new file mode 100644 index 0000000000..475237f19e --- /dev/null +++ b/Documentation/git-update-ref.txt @@ -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 |