summaryrefslogtreecommitdiff
path: root/Documentation/git-update-ref.txt
AgeCommit message (Collapse)AuthorFilesLines
2020-11-16update-ref: allow creation of multiple transactionsLibravatar Patrick Steinhardt1-1/+2
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 <ps@pks.im> Reviewed-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-07-27Modify pseudo refs through ref backend storageLibravatar Han-Wen Nienhuys1-6/+7
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 <hanwen@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-04-02update-ref: implement interactive transaction handlingLibravatar Patrick Steinhardt1-0/+26
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 <ps@pks.im> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-03-30git-update-ref.txt: add missing wordLibravatar Patrick Steinhardt1-1/+1
The description for the "verify" command is lacking a single word "is", which this commit corrects. Signed-off-by: Patrick Steinhardt <ps@pks.im> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-10-30Merge branch 'ah/doc-updates'Libravatar Junio C Hamano1-4/+4
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'
2018-10-23doc: fix formatting in git-update-refLibravatar Andreas Heiduk1-4/+4
Remove the parapgraph numbers from lines explaining the reflog format and typeset these lines in monospace. Signed-off-by: Andreas Heiduk <asheiduk@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-09-12update-ref: allow --no-deref with --stdinLibravatar Elijah Newren1-1/+1
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 <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-05-02doc: keep first level section header in upper caseLibravatar Nguyễn Thái Ngọc Duy1-1/+1
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 <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-07-21update-ref and tag: add --create-reflog argLibravatar David Turner1-1/+4
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 <dturner@twopensource.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-04-07update-ref --stdin -z: deprecate interpreting the empty string as zerosLibravatar Michael Haggerty1-6/+12
In the original version of this command, for the single case of the "update" command's <newvalue>, 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 <brad.king@kitware.com> Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-09-09update-ref: support multiple simultaneous updatesLibravatar Brad King1-1/+53
Add a --stdin signature to read update instructions from standard input and apply multiple ref updates together. Use an input format that supports any update that could be specified via the command-line, including object names like "branch:path with space". Signed-off-by: Brad King <brad.king@kitware.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-01Documentation: avoid poor-man's small caps GITLibravatar Thomas Ackermann1-1/+1
In the earlier days, we used to spell the name of the system as GIT, to simulate as if it were typeset with capital G and IT in small caps. Later we stopped doing so at around 1.6.5 days. Let's stop doing so throughout the documentation. The name to refer to the whole system (and the concept it embodies) is "Git"; the command end-users type is "git". And document this in the coding guideline. Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-07-22Merge branch 'bw/log-all-ref-updates-doc'Libravatar Junio C Hamano1-2/+3
* bw/log-all-ref-updates-doc: Documentation: clearly specify what refs are honored by core.logAllRefUpdates
2011-07-12Documentation: clearly specify what refs are honored by core.logAllRefUpdatesLibravatar Bert Wesarg1-2/+3
The documentation for logging updates in git-update-ref, doesn't make it clear that only a specific subset of refs are honored by this variable. Signed-off-by: Bert Wesarg <bert.wesarg@googlemail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-07-06Documentation: use [verse] for SYNOPSIS sectionsLibravatar Martin von Zweigbergk1-0/+1
The SYNOPSIS sections of most commands that span several lines already use [verse] to retain line breaks. Most commands that don't span several lines seem not to use [verse]. In the HTML output, [verse] does not only preserve line breaks, but also makes the section indented, which causes a slight inconsistency between commands that use [verse] and those that don't. Use [verse] in all SYNOPSIS sections for consistency. Also remove the blank lines from git-fetch.txt and git-rebase.txt to align with the other man pages. In the case of git-rebase.txt, which already uses [verse], the blank line makes the [verse] not apply to the last line, so removing the blank line also makes the formatting within the document more consistent. While at it, add single quotes to 'git cvsimport' for consistency with other commands. Signed-off-by: Martin von Zweigbergk <martin.von.zweigbergk@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-03-11doc: drop author/documentation sections from most pagesLibravatar Jeff King1-4/+0
The point of these sections is generally to: 1. Give credit where it is due. 2. Give the reader an idea of where to ask questions or file bug reports. But they don't do a good job of either case. For (1), they are out of date and incomplete. A much more accurate answer can be gotten through shortlog or blame. For (2), the correct contact point is generally git@vger, and even if you wanted to cc the contact point, the out-of-date and incomplete fields mean you're likely sending to somebody useless. So let's drop the fields entirely from all manpages except git(1) itself. We already point people to the mailing list for bug reports there, and we can update the Authors section to give credit to the major contributors and point to shortlog and blame for more information. Each page has a "This is part of git" footer, so people can follow that to the main git manpage.
2008-07-01Documentation: be consistent about "git-" versus "git "Libravatar Jonathan Nieder1-5/+5
Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-22Merge branch 'kh/update-ref'Libravatar Junio C Hamano1-1/+1
* kh/update-ref: Make old sha1 optional with git update-ref -d Clean up builtin-update-ref's option parsing
2008-06-06documentation: move git(7) to git(1)Libravatar Christian Couder1-1/+1
As the "git" man page describes the "git" command at the end-user level, it seems better to move it to man section 1. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-02Make old sha1 optional with git update-ref -dLibravatar Karl Hasselström1-1/+1
Giving the old sha1 is already optional when changing a ref, and it's quite handy when running update-ref manually. So make it optional for deleting a ref too. Signed-off-by: Karl Hasselström <kha@treskal.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-01-06Documentation: rename gitlink macro to linkgitLibravatar Dan McGee1-1/+1
Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-05-10git-update-ref: add --no-deref option for overwriting/detaching refLibravatar Sven Verdoolaege1-1/+4
git-checkout is also adapted to make use of this new option instead of the handcrafted command sequence. Signed-off-by: Sven Verdoolaege <skimo@kotnet.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-01-18Documentation: sync git.txt command list and manual page titleLibravatar Junio C Hamano1-1/+1
Also reorders a handful entries to make each list sorted alphabetically. Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-09-27update-ref: -d flag and ref creation safety.Libravatar Junio C Hamano1-2/+8
This adds -d flag to update-ref to allow safe deletion of ref. Before deleting it, the command checks if the given <oldvalue> still matches the value the caller thought the ref contained. Similarly, it also accepts 0{40} or an empty string as <oldvalue> to allow safe creation of a new ref. Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-05-19Change order of -m option to update-ref.Libravatar Shawn Pearce1-1/+1
The actual position doesn't matter but most people prefer to see options appear before the arguments. Signed-off-by: Shawn O. Pearce <spearce@spearce.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-05-17Log ref updates to logs/refs/<ref>Libravatar Shawn Pearce1-0/+26
If config parameter core.logAllRefUpdates is true or the log file already exists then append a line to ".git/logs/refs/<ref>" whenever git-update-ref <ref> is executed. Each log line contains the following information: oldsha1 <SP> newsha1 <SP> committer <LF> where committer is the current user, date, time and timezone in the standard GIT ident format. If the caller is unable to append to the log file then git-update-ref will fail without updating <ref>. An optional message may be included in the log line with the -m flag. Signed-off-by: Shawn O. Pearce <spearce@spearce.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-05-17Convert update-ref to use ref_lock API.Libravatar Shawn Pearce1-1/+1
This conversion also adds the '-m' switch to update-ref allowing the caller to record why the ref is changing. At present this is merely copied down into the ref_lock API. Signed-off-by: Shawn O. Pearce <spearce@spearce.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-03-05git/Documentation: fix SYNOPSIS style bugsLibravatar Dmitry V. Levin1-1/+1
This trivial patch fixes SYNOPSIS style bugs. Signed-off-by: Dmitry V. Levin <ldv@altlinux.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-10-04Add missing documentation.Libravatar Junio C Hamano1-0/+58
Signed-off-by: Junio C Hamano <junkio@cox.net>