]>
Commit | Line | Data |
---|---|---|
12905637 JH |
1 | git-update-ref(1) |
2 | ================= | |
3 | ||
4 | NAME | |
5 | ---- | |
c3f0baac | 6 | git-update-ref - Update the object name stored in a ref safely |
12905637 JH |
7 | |
8 | SYNOPSIS | |
9 | -------- | |
68db31cc | 10 | 'git-update-ref' [-m <reason>] (-d <ref> <oldvalue> | [--no-deref] <ref> <newvalue> [<oldvalue>]) |
12905637 JH |
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 | |
ac5409e4 JH |
23 | value is <oldvalue>. You can specify 40 "0" or an empty string |
24 | as <oldvalue> to make sure that the ref you are creating does | |
25 | not exist. | |
12905637 JH |
26 | |
27 | It also allows a "ref" file to be a symbolic pointer to another | |
28 | ref file by starting with the four-byte header sequence of | |
29 | "ref:". | |
30 | ||
31 | More importantly, it allows the update of a ref file to follow | |
32 | these symbolic pointers, whether they are symlinks or these | |
33 | "regular file symbolic refs". It follows *real* symlinks only | |
34 | if they start with "refs/": otherwise it will just try to read | |
35 | them and update them as a regular file (i.e. it will allow the | |
36 | filesystem to follow them, but will overwrite such a symlink to | |
37 | somewhere else with a regular filename). | |
38 | ||
68db31cc SV |
39 | If --no-deref is given, <ref> itself is overwritten, rather than |
40 | the result of following the symbolic pointers. | |
41 | ||
12905637 JH |
42 | In general, using |
43 | ||
44 | git-update-ref HEAD "$head" | |
45 | ||
46 | should be a _lot_ safer than doing | |
47 | ||
48 | echo "$head" > "$GIT_DIR/HEAD" | |
49 | ||
50 | both from a symlink following standpoint *and* an error checking | |
51 | standpoint. The "refs/" rule for symlinks means that symlinks | |
52 | that point to "outside" the tree are safe: they'll be followed | |
53 | for reading but not for writing (so we'll never write through a | |
54 | ref symlink to some other tree, if you have copied a whole | |
55 | archive by creating a symlink tree). | |
56 | ||
ac5409e4 JH |
57 | With `-d` flag, it deletes the named <ref> after verifying it |
58 | still contains <oldvalue>. | |
59 | ||
60 | ||
6de08ae6 SP |
61 | Logging Updates |
62 | --------------- | |
63 | If config parameter "core.logAllRefUpdates" is true or the file | |
64 | "$GIT_DIR/logs/<ref>" exists then `git-update-ref` will append | |
65 | a line to the log file "$GIT_DIR/logs/<ref>" (dereferencing all | |
66 | symbolic refs before creating the log name) describing the change | |
67 | in ref value. Log lines are formatted as: | |
68 | ||
69 | . oldsha1 SP newsha1 SP committer LF | |
70 | + | |
71 | Where "oldsha1" is the 40 character hexadecimal value previously | |
72 | stored in <ref>, "newsha1" is the 40 character hexadecimal value of | |
73 | <newvalue> and "committer" is the committer's name, email address | |
74 | and date in the standard GIT committer ident format. | |
75 | ||
76 | Optionally with -m: | |
77 | ||
78 | . oldsha1 SP newsha1 SP committer TAB message LF | |
79 | + | |
80 | Where all fields are as described above and "message" is the | |
81 | value supplied to the -m option. | |
82 | ||
83 | An update will fail (without changing <ref>) if the current user is | |
84 | unable to create a new log file, append to the existing log file | |
85 | or does not have committer information available. | |
86 | ||
12905637 JH |
87 | Author |
88 | ------ | |
89 | Written by Linus Torvalds <torvalds@osdl.org>. | |
90 | ||
91 | GIT | |
92 | --- | |
93 | Part of the gitlink:git[7] suite |