aboutsummaryrefslogtreecommitdiff
path: root/bpkg/repository-types.cxx
diff options
context:
space:
mode:
Diffstat (limited to 'bpkg/repository-types.cxx')
-rw-r--r--bpkg/repository-types.cxx206
1 files changed, 206 insertions, 0 deletions
diff --git a/bpkg/repository-types.cxx b/bpkg/repository-types.cxx
new file mode 100644
index 0000000..90efcdd
--- /dev/null
+++ b/bpkg/repository-types.cxx
@@ -0,0 +1,206 @@
+// -*- C++ -*-
+//
+// This file was generated by CLI, a command line interface
+// compiler for C++.
+//
+
+// Begin prologue.
+//
+#include <bpkg/types-parsers.hxx>
+//
+// End prologue.
+
+#include <bpkg/repository-types.hxx>
+
+#include <map>
+
+namespace bpkg
+{
+ ::bpkg::cli::usage_para
+ print_bpkg_repository_types_usage (::std::ostream& os, ::bpkg::cli::usage_para p)
+ {
+ CLI_POTENTIALLY_UNUSED (os);
+
+ if (p != ::bpkg::cli::usage_para::none)
+ os << ::std::endl;
+
+ os << "\033[1mDESCRIPTION\033[0m" << ::std::endl
+ << ::std::endl
+ << "This help topic describes the repository types recognized by \033[1mbpkg\033[0m, their" << ::std::endl
+ << "structure, and the format of their URLs. Currently three types of repositories" << ::std::endl
+ << "are supported: archive-based \033[1mpkg\033[0m, directory-based \033[1mdir\033[0m, and version" << ::std::endl
+ << "control-based \033[1mgit\033[0m." << ::std::endl
+ << ::std::endl
+ << "The repository location may specify the repository type as part of the URL" << ::std::endl
+ << "scheme component in the \033[4mtype\033[0m\033[1m+\033[0m\033[4mprotocol\033[0m\033[0m form. For example:" << ::std::endl
+ << ::std::endl
+ << "git+https://example.com/foo" << ::std::endl
+ << "dir+file:///tmp/repo" << ::std::endl
+ << ::std::endl
+ << "Note that the explicit specification is only needed when the correct type" << ::std::endl
+ << "cannot be guessed from the URL. See \033[1mbpkg-rep-add(1)\033[0m for details." << ::std::endl
+ << ::std::endl
+ << "\033[1mPKG REPOSITORIES\033[0m" << ::std::endl
+ << ::std::endl
+ << "A \033[1mpkg\033[0m repository is \033[4marchive\033[0m-based. That is, it contains a collection of various" << ::std::endl
+ << "packages/versions as archive files. For more information on the structure of" << ::std::endl
+ << "\033[1mpkg\033[0m repositories refer to The \033[1mbuild2\033[0m Package Manager Manual (bpkg). The \033[1mpkg\033[0m" << ::std::endl
+ << "repository location can be a local directory path or an \033[1mhttp(s)://\033[0m URL." << ::std::endl
+ << ::std::endl
+ << "\033[1mDIR REPOSITORIES\033[0m" << ::std::endl
+ << ::std::endl
+ << "A \033[1mdir\033[0m repository is \033[4mdirectory\033[0m-based. That is, it contains a collection of" << ::std::endl
+ << "various packages as directories but only a single version per package can be" << ::std::endl
+ << "present in such a repository. The \033[1mdir\033[0m repository location can be a local" << ::std::endl
+ << "directory path or a \033[1mfile://\033[0m URL." << ::std::endl
+ << ::std::endl
+ << "A \033[1mdir\033[0m repository is expected to contain either the \033[1mmanifest\033[0m or" << ::std::endl
+ << "\033[1mpackages.manifest\033[0m file in the root directory of the repository. If it only" << ::std::endl
+ << "contains \033[1mmanifest\033[0m, then it is assumed to be a simple, single-package repository" << ::std::endl
+ << "with the \033[1mmanifest\033[0m file being its package manifest. Otherwise, the" << ::std::endl
+ << "\033[1mpackages.manifest\033[0m file should list the locations of available packages as" << ::std::endl
+ << "described in Package List Manifest for \033[1mdir\033[0m Repositories" << ::std::endl
+ << "(bpkg#manifest-package-list-dir)." << ::std::endl
+ << ::std::endl
+ << "A \033[1mdir\033[0m repository may also contain the \033[1mrepositories.manifest\033[0m file in the root" << ::std::endl
+ << "directory of the repository. This file can be used to describe the repository" << ::std::endl
+ << "itself as well as specify its prerequisite and complement repositories. See" << ::std::endl
+ << "Repository List Manifest (bpkg#manifest-repository-list) for details on the" << ::std::endl
+ << "format and semantics of this file." << ::std::endl
+ << ::std::endl
+ << "\033[1mGIT REPOSITORIES\033[0m" << ::std::endl
+ << ::std::endl
+ << "A \033[1mgit\033[0m repository is \033[4mversion control\033[0m-based. That is, it normally contains" << ::std::endl
+ << "multiple versions of the same package (but can also contain several, usually" << ::std::endl
+ << "related, packages in the same repository)." << ::std::endl
+ << ::std::endl
+ << "A \033[1mgit\033[0m repository has the same structure and manifest files as the \033[1mdir\033[0m" << ::std::endl
+ << "repository. See Package List Manifest for \033[1mdir\033[0m Repositories" << ::std::endl
+ << "(bpkg#manifest-package-list-dir) and Repository List Manifest" << ::std::endl
+ << "(bpkg#manifest-repository-list) for details on their format and semantics." << ::std::endl
+ << ::std::endl
+ << "Theoretically, a \033[1mgit\033[0m repository may contain as many package versions as there" << ::std::endl
+ << "are commits. Practically, however, we are normally only interested in a small" << ::std::endl
+ << "subset of them while fetching and processing the necessary information for all" << ::std::endl
+ << "of them could be prohibitively expensive. As a result, by default, only" << ::std::endl
+ << "advertised tags in the \033[1mrefs/tags/v*\033[0m form where the part after \033[1mv\033[0m is also a valid" << ::std::endl
+ << "standard version (b#module-version) are considered to be sources of useful" << ::std::endl
+ << "package versions. These commits normally correspond to released versions and" << ::std::endl
+ << "are called the \033[4mdefault set\033[0m. Note that only the latest revision of each such" << ::std::endl
+ << "version is considered." << ::std::endl
+ << ::std::endl
+ << "Instead of the default set, it is possible to provide a custom set of available" << ::std::endl
+ << "versions by specifying one or more commit ids and/or references and/or" << ::std::endl
+ << "reference patterns in the repository URL fragment (see \033[1mgit-ls-remote(1)\033[0m for" << ::std::endl
+ << "details on advertised references). For example:" << ::std::endl
+ << ::std::endl
+ << "https://example.com/foo.git#v1.2.3" << ::std::endl
+ << "https://example.com/foo.git#master" << ::std::endl
+ << "https://example.com/foo.git#af234f56" << ::std::endl
+ << "https://example.com/foo.git#tags/releases/*" << ::std::endl
+ << "https://example.com/foo.git#HEAD,tags/v1.*.*,heads/feature-*" << ::std::endl
+ << ::std::endl
+ << "Furthermore, it is possible to expand (or narrow down) the default set using" << ::std::endl
+ << "the special \033[1m##\033[0m fragment notation. For example:" << ::std::endl
+ << ::std::endl
+ << "https://example.com/foo.git##HEAD - default set plus HEAD" << ::std::endl
+ << "https://example.com/foo.git##heads/* - default set plus branches" << ::std::endl
+ << "https://example.com/foo.git##-v1.* - default set minus v1.*" << ::std::endl
+ << ::std::endl
+ << "A \033[1mgit\033[0m repository URL fragment is a comma-separated list of reference filters in" << ::std::endl
+ << "the following form:" << ::std::endl
+ << ::std::endl
+ << "[\033[4mrefname\033[0m][\033[1m@\033[0m\033[4mcommit\033[0m]\033[0m" << ::std::endl
+ << ::std::endl
+ << "Either \033[4mrefname\033[0m, \033[4mcommit\033[0m, or both must be specified. If both are specified then" << ::std::endl
+ << "\033[4mrefname\033[0m is only used to minimize the amount of data fetched and \033[4mcommit\033[0m is" << ::std::endl
+ << "expected to belong to its history. For example:" << ::std::endl
+ << ::std::endl
+ << ".../foo.git#master@48fba3625d65941bb85a39061bcf795d4949c778" << ::std::endl
+ << ::std::endl
+ << "The \033[4mrefname\033[0m part can be an abbreviated commit id or an advertised reference or" << ::std::endl
+ << "reference pattern under \033[1mrefs/\033[0m. While \033[4mcommit\033[0m must be the complete, 40-characters" << ::std::endl
+ << "SHA1 that need not be advertised. For convenience, a 40-characters filter that" << ::std::endl
+ << "consists of only hexadecimal digits is assumed to be \033[4mcommit\033[0m even if not" << ::std::endl
+ << "prefixed with \033[1m@\033[0m. In an unlikely event this produces an incorrect result, the" << ::std::endl
+ << "\033[1m@\033[0m-form with omitted \033[4mcommit\033[0m can be used. For example:" << ::std::endl
+ << ::std::endl
+ << ".../foo.git#48fba3625d65941bb85a39061bcf795d4949c778 (commit id)" << ::std::endl
+ << ".../foo.git#deadbeefdeadbeefdeadbeefdeadbeefdeadbeef@ (reference)" << ::std::endl
+ << ::std::endl
+ << "The \033[4mrefname\033[0m part can use the \033[1m*\033[0m and \033[1m?\033[0m wildcard pattern characters with the" << ::std::endl
+ << "standard semantics as well as the \033[1m**\033[0m character sequence which matches in" << ::std::endl
+ << "subdirectories, recursively. For example:" << ::std::endl
+ << ::std::endl
+ << ".../foo.git#tags/v* - tags/v1.2.3 but not tags/old/v0.1.0" << ::std::endl
+ << ".../foo.git#tags/v** - tags/v1.2.3 and tags/old/v0.1.0" << ::std::endl
+ << ::std::endl
+ << "A relative \033[4mrefname\033[0m is searched for in \033[1mrefs/\033[0m, \033[1mrefs/tags/\033[0m, and \033[1mrefs/heads/\033[0m as" << ::std::endl
+ << "well as among symbolic references like \033[1mHEAD\033[0m. To anchor it to \033[1mrefs/\033[0m make it" << ::std::endl
+ << "absolute, for example:" << ::std::endl
+ << ::std::endl
+ << ".../foo.git#tags/v* - refs/tags/v1.2.3 but also refs/heads/tags/voo" << ::std::endl
+ << ".../foo.git#/tags/v* - refs/tags/v1.2.3 only" << ::std::endl
+ << ::std::endl
+ << "While a \033[4mrefname\033[0m pattern is allowed not match any references, a non-pattern that" << ::std::endl
+ << "doesn't resolve to a reference is invalid." << ::std::endl
+ << ::std::endl
+ << "If a \033[4mrefname\033[0m starts with minus (\033[1m-\033[0m) then it is treated as an exclusion filter --" << ::std::endl
+ << "any references that it matches are excluded from the set included by the" << ::std::endl
+ << "preceding filters (or the default set). For example:" << ::std::endl
+ << ::std::endl
+ << ".../foo.git#v*,-v1.* - exclude v1.* from v*" << ::std::endl
+ << ".../foo.git##-v1.* - exclude v1.* from default set" << ::std::endl
+ << ::std::endl
+ << "To support specifying literal leading minus, a \033[4mrefname\033[0m that starts with plus" << ::std::endl
+ << "(\033[1m+\033[0m) is treated as an inclusion filter. For example:" << ::std::endl
+ << ::std::endl
+ << ".../foo.git#+x - include x" << ::std::endl
+ << ".../foo.git#+-x - include -x" << ::std::endl
+ << ".../foo.git#++x - include +x" << ::std::endl
+ << ::std::endl
+ << "Currently supported \033[1mgit\033[0m protocols are \033[1mgit://\033[0m, \033[1mssh://\033[0m (but not scp\033[0m pseudo-URL" << ::std::endl
+ << "syntax), \033[1mhttp://\033[0m, and \033[1mhttps://\033[0m for remote repositories and \033[1mfile://\033[0m for local" << ::std::endl
+ << "repositories. While \033[1mbpkg\033[0m tries to minimize the amount of information (history)" << ::std::endl
+ << "fetched, it is not always possible for some protocols and/or server" << ::std::endl
+ << "configurations, as discussed next." << ::std::endl
+ << ::std::endl
+ << "A \033[1mgit\033[0m repository accessible via \033[1mhttp(s)://\033[0m can use either \033[4mdumb\033[0m or \033[4msmart\033[0m" << ::std::endl
+ << "protocol (refer to the \033[1mgit\033[0m documentation for details). The dumb protocol" << ::std::endl
+ << "provides only limited support for fetch minimization and if this protocol is" << ::std::endl
+ << "used, then \033[1mbpkg\033[0m has no choice but to download a substantial amount of history." << ::std::endl
+ << ::std::endl
+ << "The smart protocol allows fetching of minimal history for tags and branches." << ::std::endl
+ << "Whether this is also possible for (all) commit ids depends on whether the" << ::std::endl
+ << "server is configured to allow fetching unadvertised commits. For details, refer" << ::std::endl
+ << "to the \033[1muploadpack.allowReachableSHA1InWant\033[0m and \033[1muploadpack.allowAnySHA1InWant\033[0m" << ::std::endl
+ << "\033[1mgit\033[0m configuration values." << ::std::endl
+ << ::std::endl
+ << "The \033[1mgit://\033[0m and \033[1mssh://\033[0m protocols are similar to smart \033[1mhttp://\033[0m in that they" << ::std::endl
+ << "support fetching minimal history for tags and branches and may or may not" << ::std::endl
+ << "support this for commit ids depending on the server configuration. Note," << ::std::endl
+ << "however, that unlike for \033[1mhttp(s)://\033[0m, for these protocols \033[1mbpkg\033[0m does not try to" << ::std::endl
+ << "sense if fetching unadvertised commits is allowed and always assumes that it is" << ::std::endl
+ << "not. Also note that the sensed or assumed protocol capabilities can be" << ::std::endl
+ << "overridden for a \033[1mgit\033[0m repository URL prefix using the \033[1m--git-capabilities\033[0m option" << ::std::endl
+ << "(\033[1mbpkg-common-options(1)\033[0m)." << ::std::endl
+ << ::std::endl
+ << "Based on this information, to achieve optimal results the recommended protocol" << ::std::endl
+ << "for remote repositories is smart \033[1mhttps://\033[0m. Additionally, if you are planning to" << ::std::endl
+ << "refer to unadvertised commit ids, then also consider configuring the server to" << ::std::endl
+ << "allow fetching unadvertised commits." << ::std::endl
+ << ::std::endl
+ << "The \033[1mfile://\033[0m protocol has the same fetch minimization support as \033[1mgit://\033[0m and is" << ::std::endl
+ << "therefore treated the same." << ::std::endl;
+
+ p = ::bpkg::cli::usage_para::text;
+
+ return p;
+ }
+}
+
+// Begin epilogue.
+//
+//
+// End epilogue.
+