diff options
| -rw-r--r-- | bpkg/bpkg.cli | 8 | ||||
| -rw-r--r-- | bpkg/rep-add.cli | 110 | ||||
| -rw-r--r-- | bpkg/rep-info.cli | 7 |
3 files changed, 109 insertions, 16 deletions
diff --git a/bpkg/bpkg.cli b/bpkg/bpkg.cli index d2d543f..6b705d1 100644 --- a/bpkg/bpkg.cli +++ b/bpkg/bpkg.cli @@ -51,13 +51,14 @@ namespace bpkg amalgamation that contains packages as subprojects. A \i{bpkg package} is an archive or directory that contains a \cb{build2} - project plus a package \cb{manifest} file. \cb{bpkg} can either use + project plus the package \cb{manifest} file. \cb{bpkg} can either use package archives/directories directly from the filesystem or it can fetch archives from repositories. A \i{bpkg repository} is a collection of packages as well as prerequisite - and complement repositories. A repository is identified by its location, - which can be a local filesystem path or a remote HTTP or HTTPS URL. + and complement repositories. Both \i{archive} and \i{version + control}-based repository types are supported. A repository is identified + by its location which can be a local filesystem path or a URL. A typical \cb{bpkg} workflow would consist of the following steps. @@ -76,6 +77,7 @@ namespace bpkg \ bpkg add https://pkg.cppget.org/1/stable + bpkg add https://git.build2.org/hello/libhello.git#master \ Repeat this command to add more repositories. diff --git a/bpkg/rep-add.cli b/bpkg/rep-add.cli index eddea45..7f9bb09 100644 --- a/bpkg/rep-add.cli +++ b/bpkg/rep-add.cli @@ -13,7 +13,7 @@ include <bpkg/configuration.cli>; namespace bpkg { { - "<options> <rep>", + "<options> <rep> <tag> <branch> <commit-id>", "\h|SYNOPSIS| @@ -22,9 +22,106 @@ namespace bpkg \h|DESCRIPTION| The \cb{rep-add} command adds the specified package repository to the - configuration. Note that it doesn't fetch the list of available packages - for the newly added repository. For that, use the \l{bpkg-rep-fetch(1)} - command, normally, after adding all the repositories you wish to use." + configuration. The repository location <rep> is a URL or a directory + path. + + Note that this command doesn't fetch the list of available packages for + the newly added repository. For that, use the \l{bpkg-rep-fetch(1)} + command, normally, after adding all the repositories you wish to use. + + Currently two types of repositories are supported: \i{bpkg} and \i{git}. + Normally the repository type can be automatically guessed by examining + its URL (for example, the presence of the \cb{.git} extension) or, in + case of a local repository, its content (for example, the presence of the + \cb{.git/} subdirectory). Without any identifying information the bpkg + type is assumed unless explicitly specified with the \cb{--type} option. + + A bpkg repository is \i{archive}-based. That is, it contains a collection + of various packages/versions as archive files. For more information on + the structure of bpkg repositories refer to the \cb{bpkg} manual. + + A git repository is \i{version control}-based. That is, it normally + contains multiple versions of the same package (but can also contain + several packages in the same repository). + + Theoretically, a git repository may contain as many package versions as + there are commits. Practically, however, we are normally only interested + in a small subset of them while fetching and processing the necessary + information for all of them could be prohibitively expensive. As a + result, a git repository URL must include the fragment component that + restricts the set of versions to consider as available. While in the + future it will be possible to specify multiple available versions, + currently the fragment must identify a single version using one of the + following forms: + + \ + #<tag> + #<branch> + #[<branch>]@<commit-id> + \ + + In the last form <branch> is optional and is only used to minimize the + amount of data to fetch. If specified, then the commit must belong to its + history. Note also that no abbreviated commit ids are supported and + <commit-id> must be the complete, 40-character SHA1 string. Below are + some examples of git repository URLs: + + \ + https://example.com/foo.git#v1.2.3 + https://example.com/foo.git#master + https://example.com/foo.git#@48fba3625d65941bb85a39061bcf795d4949c778 + https://example.com/foo.git#bar@48fba3625d65941bb85a39061bcf795d4949c778 + \ + + A git repository is expected to contain either the \cb{manifest} or + \cb{packages} file in the root directory of the repository. If it only + contains \cb{manifest}, then it is assumed to be a single-package + repository with the \cb{manifest} file being its package manifest. + Otherwise the \cb{packages} file should list the available packages as + directory paths relative to the repository root (which in turn should + contain the \cb{manifest} files). The \cb{packages} file is a manifest + (see the \cb{bpkg} manual for details on the manifest file format) that + should contain one or more \cb{location} values in the POSIX path + representation. For example: + + \ + : 1 + location: src/libfoo/ + location: src/foo/ + \ + + Supported git protocols are \cb{git://}, \cb{http://}, and \cb{https://} + for remote repositories and \cb{file://} for local repositories. While + \cb{bpkg} tries to minimize the amount of information (history) fetched, + it is not always possible for some protocols and/or server + configurations, as discussed next. + + A git repository accessible via \cb{http(s)://} can use either \i{dumb} + or \i{smart} protocol (refer to the \cb{git} documentation for details). + The dumb protocol provides only limited support for fetch minimization + and if this protocol is used, then \cb{bpkg} has no choice but to + download a substantial amount of history. + + The smart protocol allows fetching of minimal history for tags and + branches. Whether this is also possible for (all) commit ids depends on + whether the server is configured to allow fetching unadvertised commits. + For details, refer to the \cb{uploadpack.allowReachableSHA1InWant} and + \cb{uploadpack.allowAnySHA1InWant} \cb{git} configuration values. + + The \cb{git://} protocol is similar to smart \cb{http://} in that it + supports fetching minimal history for tags and branches and may or may + not support this for commit ids depending on the server configuration. + Note, however, that unlike for \cb{http(s)://}, for this protocol + \cb{bpkg} does not try to sense if fetching unadvertised commits is + allowed and always assumes that it is not. + + Based on this information, to achieve optimal results the recommended + protocol for remote repositories is smart \cb{https://}. Additionally, if + you are planning to refer to commit ids, then also consider configuring + the server to allow fetching unadvertised commits. + + The \cb{file://} protocol has the same fetch minimization support as + \cb{git://} and is therefore treated the same." } class rep_add_options: configuration_options @@ -35,10 +132,7 @@ namespace bpkg { "<type>", "Specify the repository type with valid values being \cb{bpkg} and - \cb{git}. Normally the repository type can be automatically guessed by - examining its URL (for example, the presence of the \cb{.git} - extension) or, in case of a local repository, its content (for example, - the presence of the \cb{.git} subdirectory)." + \cb{git}." } }; } diff --git a/bpkg/rep-info.cli b/bpkg/rep-info.cli index d2ce9b6..5c11f4f 100644 --- a/bpkg/rep-info.cli +++ b/bpkg/rep-info.cli @@ -24,7 +24,7 @@ namespace bpkg The \cb{rep-info} command prints various information about the specified repository. By default it print the repository's name and location as the first line. If the repository is signed, the certificate information - (name/organization/email) is printed as the next line following by the + (name/organization/email) is printed as the next line followed by the certificate fingerprint. Then comes the list of complement and prerequisite repositories followed by the list of available packages. @@ -97,10 +97,7 @@ namespace bpkg { "<type>", "Specify the repository type with valid values being \cb{bpkg} and - \cb{git}. Normally the repository type can be automatically guessed by - examining its URL (for example, the presence of the \cb{.git} - extension) or, in case of a local repository, its content (for example, - the presence of the \cb{.git} subdirectory)." + \cb{git}. Refer to \l{bpkg-rep-add(1)} for details." } string --directory|-d // String to allow empty value. |