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