aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2018-02-10 12:19:27 +0200
committerKaren Arutyunov <karen@codesynthesis.com>2018-02-12 17:35:01 +0300
commit1ac50a35f4183cd7cd4bae0b310e20474a2d1f69 (patch)
tree2dfc7a4fd9d69165b4c9b9d5bd91868bdd266f99
parentb7763416f8a1e4940a10336d3a8b9fbbb879f414 (diff)
Document git repository-related functionality
-rw-r--r--bpkg/bpkg.cli8
-rw-r--r--bpkg/rep-add.cli110
-rw-r--r--bpkg/rep-info.cli7
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.