git/Documentation/git-update-ref.txt, branch v2.33.6

update-ref: allow creation of multiple transactions

2020-11-16T21:44:01Z

While git-update-ref has recently grown commands which allow interactive control of transactions in e48cf33b61 (update-ref: implement interactive transaction handling, 2020-04-02), it is not yet possible to create multiple transactions in a single session. To do so, one currently still needs to invoke the executable multiple times. This commit addresses this shortcoming by allowing the "start" command to create a new transaction if the current transaction has already been either committed or aborted. Signed-off-by: Patrick Steinhardt Reviewed-by: Jeff King Signed-off-by: Junio C Hamano

Modify pseudo refs through ref backend storage

2020-07-27T17:06:49Z

The previous behavior was introduced in commit 74ec19d4be ("pseudorefs: create and use pseudoref update and delete functions", Jul 31, 2015), with the justification "alternate ref backends still need to store pseudorefs in GIT_DIR". Refs such as REBASE_HEAD are read through the ref backend. This can only work consistently if they are written through the ref backend as well. Tooling that works directly on files under .git should be updated to use git commands to read refs instead. The following behaviors change: * Updates to pseudorefs (eg. ORIG_HEAD) with core.logAllRefUpdates=always will create reflogs for the pseudoref. * non-HEAD pseudoref symrefs are also dereferenced on deletion. Update t1405 accordingly. Signed-off-by: Han-Wen Nienhuys Signed-off-by: Junio C Hamano

update-ref: implement interactive transaction handling

2020-04-02T18:09:49Z

The git-update-ref(1) command can only handle queueing transactions right now via its "--stdin" parameter, but there is no way for users to handle the transaction itself in a more explicit way. E.g. in a replicated scenario, one may imagine a coordinator that spawns git-update-ref(1) for multiple repositories and only if all agree that an update is possible will the coordinator send a commit. Such a transactional session could look like > start < start: ok > update refs/heads/master $OLD $NEW > prepare < prepare: ok # All nodes have returned "ok" > commit < commit: ok or > start < start: ok > create refs/heads/master $OLD $NEW > prepare < fatal: cannot lock ref 'refs/heads/master': reference already exists # On all other nodes: > abort < abort: ok In order to allow for such transactional sessions, this commit introduces four new commands for git-update-ref(1), which matches those we have internally already with the exception of "start": - start: start a new transaction - prepare: prepare the transaction, that is try to lock all references and verify their current value matches the expected one - commit: explicitly commit a session, that is update references to match their new expected state - abort: abort a session and roll back all changes By design, git-update-ref(1) will commit as soon as standard input is being closed. While fine in a non-transactional world, it is definitely unexpected in a transactional world. Because of this, as soon as any of the new transactional commands is used, the default will change to aborting without an explicit "commit". To avoid a race between queueing updates and the first "prepare" that starts a transaction, the "start" command has been added to start an explicit transaction. Add some tests to exercise this new functionality. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano

git-update-ref.txt: add missing word

2020-03-30T17:34:11Z

The description for the "verify" command is lacking a single word "is", which this commit corrects. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano

Merge branch 'ah/doc-updates'

2018-10-30T06:43:47Z

Doc updates. * ah/doc-updates: doc: fix formatting in git-update-ref doc: fix indentation of listing blocks in gitweb.conf.txt doc: fix descripion for 'git tag --format' doc: fix inappropriate monospace formatting doc: fix ASCII art tab spacing doc: clarify boundaries of 'git worktree list --porcelain'

doc: fix formatting in git-update-ref

2018-10-23T03:23:09Z

Remove the parapgraph numbers from lines explaining the reflog format and typeset these lines in monospace. Signed-off-by: Andreas Heiduk Signed-off-by: Junio C Hamano

update-ref: allow --no-deref with --stdin

2018-09-12T22:17:17Z

If passed both --no-deref and --stdin, update-ref would error out with a general usage message that did not at all suggest these options were incompatible. The manpage for update-ref did suggest through its synopsis line that --no-deref and --stdin were incompatible, but it sadly also incorrectly suggested that -d and --no-deref were incompatible. So the help around the --no-deref option is buggy in a few ways. The --stdin option did provide a different mechanism for avoiding dereferencing symbolic-refs: adding a line reading option no-deref before every other directive in the input. (Technically, if the user wants to do the extra work of first determining which refs they want to update or delete are symbolic, then they only need to put the extra "option no-deref" lines before the updates of those refs. But in some cases, that's more work than just adding the "option no-deref" before every other directive.) It's easier to allow the user to just pass --no-deref along with --stdin in order to tell update-ref that the user doesn't want any symbolic ref to be dereferenced. It also makes the update-ref documentation simpler. Implement that, and update the documentation to match. Signed-off-by: Elijah Newren Signed-off-by: Junio C Hamano

doc: keep first level section header in upper case

2018-05-02T08:03:33Z

When formatted as a man page, 1st section header is always in upper case even if we write it otherwise. Make all 1st section headers uppercase to keep it close to the final output. This does affect html since case is kept there, but I still think it's a good idea to maintain a consistent style for 1st section headers. Some sections perhaps should become second sections instead, where case is kept, and for better organization. I will update if anyone has suggestions about this. While at there I also make some header more consistent (e.g. examples vs example) and fix a couple minor things here and there. Signed-off-by: Nguyễn Thái Ngọc Duy Signed-off-by: Junio C Hamano

update-ref and tag: add --create-reflog arg

2015-07-21T21:08:35Z

Allow the creation of a ref (e.g. stash) with a reflog already in place. For most refs (e.g. those under refs/heads), this happens automatically, but for others, we need this option. Currently, git does this by pre-creating the reflog, but alternate ref backends might store reflogs somewhere other than .git/logs. Code that now directly manipulates .git/logs should instead use git plumbing commands. I also added --create-reflog to git tag, just for completeness. In a moment, we will use this argument to make git stash work with alternate ref backends. Signed-off-by: David Turner Signed-off-by: Junio C Hamano

update-ref --stdin -z: deprecate interpreting the empty string as zeros

2014-04-07T19:09:13Z

In the original version of this command, for the single case of the "update" command's , the empty string was interpreted as being equivalent to 40 "0"s. This shorthand is unnecessary (binary input will usually be generated programmatically anyway), and it complicates the parser and the documentation. So gently deprecate this usage: remove its description from the documentation and emit a warning if it is found. But for reasons of backwards compatibility, continue to accept it. Helped-by: Brad King Signed-off-by: Michael Haggerty Signed-off-by: Junio C Hamano