projects / thirdparty / git.git / blame
| Commit | Line | Data |
|---|---|---|
| 12905637 JH |
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 |