summaryrefslogtreecommitdiff
path: root/Documentation/git-remote-helpers.txt
AgeCommit message (Collapse)AuthorFilesLines
2012-04-26docs: stop using asciidoc no-inline-literalLibravatar Jeff King1-4/+4
In asciidoc 7, backticks like `foo` produced a typographic effect, but did not otherwise affect the syntax. In asciidoc 8, backticks introduce an "inline literal" inside which markup is not interpreted. To keep compatibility with existing documents, asciidoc 8 has a "no-inline-literal" attribute to keep the old behavior. We enabled this so that the documentation could be built on either version. It has been several years now, and asciidoc 7 is no longer in wide use. We can now decide whether or not we want inline literals on their own merits, which are: 1. The source is much easier to read when the literal contains punctuation. You can use `master~1` instead of `master{tilde}1`. 2. They are less error-prone. Because of point (1), we tend to make mistakes and forget the extra layer of quoting. This patch removes the no-inline-literal attribute from the Makefile and converts every use of backticks in the documentation to an inline literal (they must be cleaned up, or the example above would literally show "{tilde}" in the output). Problematic sites were found by grepping for '`.*[{\\]' and examined and fixed manually. The results were then verified by comparing the output of "html2text" on the set of generated html pages. Doing so revealed that in addition to making the source more readable, this patch fixes several formatting bugs: - HTML rendering used the ellipsis character instead of literal "..." in code examples (like "git log A...B") - some code examples used the right-arrow character instead of '->' because they failed to quote - api-config.txt did not quote tilde, and the resulting HTML contained a bogus snippet like: <tt><sub></tt> foo <tt></sub>bar</tt> which caused some parsers to choke and omit whole sections of the page. - git-commit.txt confused ``foo`` (backticks inside a literal) with ``foo'' (matched double-quotes) - mentions of `A U Thor <author@example.com>` used to erroneously auto-generate a mailto footnote for author@example.com - the description of --word-diff=plain incorrectly showed the output as "[-removed-] and {added}", not "{+added+}". - using "prime" notation like: commit `C` and its replacement `C'` confused asciidoc into thinking that everything between the first backtick and the final apostrophe were meant to be inside matched quotes - asciidoc got confused by the escaping of some of our asterisks. In particular, `credential.\*` and `credential.<url>.\*` properly escaped the asterisk in the first case, but literally passed through the backslash in the second case. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-09-01(short) documentation for the testgit remote helperLibravatar Matthieu Moy1-0/+2
While it's not a command meant to be used by actual users (hence, not mentionned in git(1)), this command is a very precious help for remote-helpers authors. The best place for such technical doc is the source code, but users may not find it without a link in a manpage. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Acked-by: Sverre Rabbelier <srabbelier@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-09-01Documentation/git-remote-helpers: explain how import works with multiple refsLibravatar Matthieu Moy1-1/+21
This is important for two reasons: * when two "import" lines follow each other, only one "done" command should be issued in the fast-import stream, not one per "import". * The blank line terminating an import command should not be confused with the one terminating the sequence of commands. While we're there, illustrate the corresponding explanation for push batches with an example. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Acked-by: Sverre Rabbelier <srabbelier@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-08-29Documentation/remote-helpers: explain capabilities firstLibravatar Jonathan Nieder1-30/+129
The current remote helper documentation is from the perspective of git, so to speak: it presents a full menu of commands for a person invoking a remote helper to choose from. In practice, that's less useful than it could be, since the daunted novice remote-helper author probably just wanted a list of commands needs to implement to get started. So preface the command list with an overview of each capability, its purpose, and what commands it requires. As a side effect, this makes it a little clearer that git doesn't choose arbitrary commands to run, even if the remote helper advertises all capabilities --- instead, there are well defined command sequences for various tasks. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-08-01Merge branch 'sr/transport-helper-fix'Libravatar Junio C Hamano1-0/+3
* sr/transport-helper-fix: (21 commits) transport-helper: die early on encountering deleted refs transport-helper: implement marks location as capability transport-helper: Use capname for refspec capability too transport-helper: change import semantics transport-helper: update ref status after push with export transport-helper: use the new done feature where possible transport-helper: check status code of finish_command transport-helper: factor out push_update_refs_status fast-export: support done feature fast-import: introduce 'done' command git-remote-testgit: fix error handling git-remote-testgit: only push for non-local repositories remote-curl: accept empty line as terminator remote-helpers: export GIT_DIR variable to helpers git_remote_helpers: push all refs during a non-local export transport-helper: don't feed bogus refs to export push git-remote-testgit: import non-HEAD refs t5800: document some non-functional parts of remote helpers t5800: use skip_all instead of prereq t5800: factor out some ref tests ...
2011-07-19remote-helpers: export GIT_DIR variable to helpersLibravatar Dmitry Ivankov1-0/+3
The gitdir capability is recognized by git and can be used to tell the helper where the .git directory is. But it is not mentioned in the documentation and considered worse than if gitdir was passed via GIT_DIR environment variable. Remove support for the gitdir capability and export GIT_DIR instead. Teach testgit to use env instead of the now-removed gitdir command. [sr: fixed up documentation] Signed-off-by: Dmitry Ivankov <divanorama@gmail.com> Signed-off-by: Sverre Rabbelier <srabbelier@gmail.com> Acked-by: Jeff King <peff@peff.net> 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-05-30Documentation: do not misinterpret refspecs as bold textLibravatar Jonathan Nieder1-3/+3
In v1.7.3.3~2 (Documentation: do not misinterpret pull refspec as bold text, 2010-12-03) many uses of asterisks in expressions like "refs/heads/*:refs/svn/origin/branches/*" were escaped as {asterisk} to avoid being treated as delimiters for bold text, but these two were missed. Signed-off-by: Jonathan Nieder <jrnieder@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.
2011-02-17Make <identifier> lowercase in DocumentationLibravatar Michael J Gruber1-3/+3
Leaving uppercase abbreviations (e.g. URL) and an identifier named after an upercase env variable (CVSROOT) in place, this adjusts the few remaining cases and fixes an unidentified identifier along the way. Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-04-18Documentation/remote-helpers: Fix typos and improve languageLibravatar Ramkumar Ramachandra1-28/+23
Fix some typos and errors in grammar and tense. Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com> Acked-by: Sverre Rabbelier <srabbelier@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-04-18Fixup: Second argument may be any arbitrary stringLibravatar Ramkumar Ramachandra1-3/+2
This is intended to be a fixup for commit ad466d1 in pu. As Jonathan Neider pointed out, the second argument may be any arbitrary string, and need not conform to any URL-like shape. Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com> Acked-by: Sverre Rabbelier <srabbelier@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-04-18Documentation/remote-helpers: Add invocation sectionLibravatar Ramkumar Ramachandra1-1/+34
Add an 'Invocation' section to specify what the command line arguments mean. Also include a link to git-remote in the 'See Also' section. Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com> Acked-by: Sverre Rabbelier <srabbelier@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-04-18Documentation/remote-helpers: Rewrite descriptionLibravatar Ramkumar Ramachandra1-6/+27
Rewrite the description section to describe what exactly remote helpers are and the need for them. Also mention the curl family of remote helpers as an example. [jc: with readability fixes from Jonathan squashed in] Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Acked-by: Sverre Rabbelier <srabbelier@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-01-31Fix typos in technical documentation.Libravatar Ralf Wildenhues1-1/+1
Signed-off-by: Ralf Wildenhues <Ralf.Wildenhues@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-12-28Support remote helpers implementing smart transportsLibravatar Ilari Liusvaara1-1/+24
Signed-off-by: Ilari Liusvaara <ilari.liusvaara@elisanet.fi> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-12-09Support mandatory capabilitiesLibravatar Ilari Liusvaara1-1/+4
Add support for marking capability as mandatory for hosting git version to understand. This is useful for helpers which require various types of assistance from main git binary. Signed-off-by: Ilari Liusvaara <ilari.liusvaara@elisanet.fi> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-12-06Merge branch 'master' into il/vcs-helperLibravatar Junio C Hamano1-4/+81
* master: (334 commits) bash: update 'git commit' completion Git 1.6.5.5 Fix diff -B/--dirstat miscounting of newly added contents reset: improve worktree safety valves Documentation: Avoid use of xmlto --stringparam archive: clarify description of path parameter rerere: don't segfault on failure to open rr-cache Prepare for 1.6.5.5 gitweb: Describe (possible) gitweb.js minification in gitweb/README Documentation: xmlto 0.0.18 does not know --stringparam Fix crasher on encountering SHA1-like non-note in notes tree t9001: use older Getopt::Long boolean prefix '--no' rather than '--no-' t4201: use ISO8859-1 rather than ISO-8859-1 Git 1.6.5.4 Unconditionally set man.base.url.for.relative.links Documentation/Makefile: allow man.base.url.for.relative.link to be set from Make Git 1.6.6-rc1 git-pull.sh: Fix call to git-merge for new command format Prepare for 1.6.5.4 merge: do not add standard message when message is given with -m option ... Conflicts: Documentation/git-remote-helpers.txt Makefile builtin-ls-remote.c builtin-push.c transport-helper.c Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-11-17Allow helpers to report in "list" command that the ref is unchangedLibravatar Daniel Barkalow1-1/+3
Helpers may use a line like "? name unchanged" to specify that there is nothing new at that name, without any git-specific code to determine the correct response. Signed-off-by: Daniel Barkalow <barkalow@iabervon.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-11-17Allow helper to map private ref names into normal namesLibravatar Daniel Barkalow1-1/+15
This allows a helper to say that, when it handles "import refs/heads/topic", the script it outputs will actually write to refs/svn/origin/branches/topic; therefore, transport-helper should read it from the latter location after git-fast-import completes. Signed-off-by: Daniel Barkalow <barkalow@iabervon.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-11-17Add support for "import" helper commandLibravatar Daniel Barkalow1-0/+10
This command, supported if the "import" capability is advertized, allows a helper to support fetching by outputting a git-fast-import stream. If both "fetch" and "import" are advertized, git itself will use "fetch" (although other users may use "import" in this case). Signed-off-by: Daniel Barkalow <barkalow@iabervon.org> Signed-off-by: Sverre Rabbelier <srabbelier@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-10-30Move WebDAV HTTP push under remote-curlLibravatar Shawn O. Pearce1-1/+32
The remote helper interface now supports the push capability, which can be used to ask the implementation to push one or more specs to the remote repository. For remote-curl we implement this by calling the existing WebDAV based git-http-push executable. Internally the helper interface uses the push_refs transport hook so that the complexity of the refspec parsing and matching can be reused between remote implementations. When possible however the helper protocol uses source ref name rather than the source SHA-1, thereby allowing the helper to access this name if it is useful. >From Clemens Buchacher <drizzd@aon.at>: update http tests according to remote-curl capabilities o Pushing packed refs is now fixed. o The transport helper fails if refs are already up-to-date. Add a test for that. o The transport helper will notice if refs are already up-to-date. We therefore need to update server info in the unpacked-refs test. o The transport helper will purge deleted branches automatically. o Use a variable ($ORIG_HEAD) instead of full SHA-1 name. Signed-off-by: Tay Ray Chuan <rctay89@gmail.com> Signed-off-by: Clemens Buchacher <drizzd@aon.at> Signed-off-by: Shawn O. Pearce <spearce@spearce.org> CC: Daniel Barkalow <barkalow@iabervon.org> CC: Mike Hommey <mh@glandium.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-10-30remote-helpers: Support custom transport optionsLibravatar Shawn O. Pearce1-0/+38
Some transports, like the native pack transport implemented by fetch-pack, support useful features like depth or include tags. These should be exposed if the underlying helper knows how to use them. Signed-off-by: Shawn O. Pearce <spearce@spearce.org> CC: Daniel Barkalow <barkalow@iabervon.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-10-30remote-helpers: Fetch more than one ref in a batchLibravatar Shawn O. Pearce1-4/+10
Some network protocols (e.g. native git://) are able to fetch more than one ref at a time and reduce the overall transfer cost by combining the requests into a single exchange. Instead of feeding each fetch request one at a time to the helper, feed all of them at once so the helper can decide whether or not it should batch them. Signed-off-by: Shawn O. Pearce <spearce@spearce.org> CC: Daniel Barkalow <barkalow@iabervon.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-08-05Add support for external programs for handling native fetchesLibravatar Daniel Barkalow1-0/+71
transport_get() can call transport_native_helper_init() to have list and fetch-ref operations handled by running a separate program as: git remote-<something> <remote> [<url>] This program then accepts, on its stdin, "list" and "fetch <hex> <name>" commands; the former prints out a list of available refs and either their hashes or what they are symrefs to, while the latter fetches them into the local object database and prints a newline when done. Signed-off-by: Daniel Barkalow <barkalow@iabervon.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>