diff options
Diffstat (limited to 'Documentation/git-update-ref.txt')
| -rw-r--r-- | Documentation/git-update-ref.txt | 62 |
1 files changed, 60 insertions, 2 deletions
diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index d377a35243..c8f5ae5cb3 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -8,7 +8,7 @@ git-update-ref - Update the object name stored in a ref safely SYNOPSIS -------- [verse] -'git update-ref' [-m <reason>] (-d <ref> [<oldvalue>] | [--no-deref] <ref> <newvalue> [<oldvalue>]) +'git update-ref' [-m <reason>] (-d <ref> [<oldvalue>] | [--no-deref] <ref> <newvalue> [<oldvalue>] | --stdin [-z]) DESCRIPTION ----------- @@ -58,6 +58,64 @@ archive by creating a symlink tree). With `-d` flag, it deletes the named <ref> after verifying it still contains <oldvalue>. +With `--stdin`, update-ref reads instructions from standard input and +performs all modifications together. Specify commands of the form: + + update SP <ref> SP <newvalue> [SP <oldvalue>] LF + create SP <ref> SP <newvalue> LF + delete SP <ref> [SP <oldvalue>] LF + verify SP <ref> [SP <oldvalue>] LF + option SP <opt> LF + +Quote fields containing whitespace as if they were strings in C source +code; i.e., surrounded by double-quotes and with backslash escapes. +Use 40 "0" characters or the empty string to specify a zero value. To +specify a missing value, omit the value and its preceding SP entirely. + +Alternatively, use `-z` to specify in NUL-terminated format, without +quoting: + + update SP <ref> NUL <newvalue> NUL [<oldvalue>] NUL + create SP <ref> NUL <newvalue> NUL + delete SP <ref> NUL [<oldvalue>] NUL + verify SP <ref> NUL [<oldvalue>] NUL + option SP <opt> NUL + +In this format, use 40 "0" to specify a zero value, and use the empty +string to specify a missing value. + +In either format, values can be specified in any form that Git +recognizes as an object name. Commands in any other format or a +repeated <ref> produce an error. Command meanings are: + +update:: + Set <ref> to <newvalue> after verifying <oldvalue>, if given. + Specify a zero <newvalue> to ensure the ref does not exist + after the update and/or a zero <oldvalue> to make sure the + ref does not exist before the update. + +create:: + Create <ref> with <newvalue> after verifying it does not + exist. The given <newvalue> may not be zero. + +delete:: + Delete <ref> after verifying it exists with <oldvalue>, if + given. If given, <oldvalue> may not be zero. + +verify:: + Verify <ref> against <oldvalue> but do not change it. If + <oldvalue> zero or missing, the ref must not exist. + +option:: + Modify behavior of the next command naming a <ref>. + The only valid option is `no-deref` to avoid dereferencing + a symbolic ref. + +If all <ref>s can be locked with matching <oldvalue>s +simultaneously, all modifications are performed. Otherwise, no +modifications are performed. Note that while each individual +<ref> is updated or deleted atomically, a concurrent reader may +still see a subset of the modifications. Logging Updates --------------- @@ -73,7 +131,7 @@ in ref value. Log lines are formatted as: Where "oldsha1" is the 40 character hexadecimal value previously stored in <ref>, "newsha1" is the 40 character hexadecimal value of <newvalue> and "committer" is the committer's name, email address -and date in the standard GIT committer ident format. +and date in the standard Git committer ident format. Optionally with -m: |