Document changes in gitlab:: package sources

r-lib · Apr 4, 2024 · 019393c · 019393c
1 parent e5e84fd
commit 019393c
Show file tree

Hide file tree

Showing 5 changed files with 45 additions and 12 deletions.
diff --git a/NEWS.md b/NEWS.md
@@ -1,5 +1,8 @@
 # pkgdepends (development version)
 
+* pkgdepends now supports `gitlab::` package sources better, by adding
+  explicit syntax to specify subdirectories (#353, @dgkf).
+
 # pkgdepends 0.7.2
 
 * pkgdepends now supports the `*` wildcard for parameter specifications,

diff --git a/inst/docs/pkg-refs.rds b/inst/docs/pkg-refs.rds
diff --git a/man/pkg_refs.Rd b/man/pkg_refs.Rd
diff --git a/tools/doc/pkg-refs.Rmd b/tools/doc/pkg-refs.Rmd
@@ -260,24 +260,31 @@ A GitHub remote string can also be used instead of an URL, for example:
 Packages from a GitLab repository. Full syntax:
 
 ```
-[<package>=][github::]<username>/<repository>[/<subdir>][<detail>]
+[<package>=][github::]<project-path>/<repository>[/-/<subdir>][<detail>]
 ```
 
 - `<package>` is the name of the package. If this is missing, then
   the name of the repository is used.
-- `<username>` is a GitLab username or group name.
-- `<repository>` is the name of the repository.
+- `<project-path>` is a typically the GitLab username or group name, but
+  it may contain subgroups.
+- `<repository>` is the name of the repository, or the project in GitLab
+  terminology.
 - `<subdir>` optional subdirectory, if the package is within a
-  subdirectory in the repository.
+  subdirectory in the repository. Note that for GitLab, this must come
+  after a `/-` prefix, to be able to distinguish it from subgroups.
 - `<detail>` may specify a git branch, tag or (prefix of) a commit hash.
 
 If `<detail>` is missing, then the latest commit of the _default_
 branch is used.
 
+`gitlab::` supports git submodules, see the `git-submodules` configuration
+entry.
+
 Examples:
 ```
 gitlab::gaborcsardi/cli
 gitlab::r-hub/filelock@main
+gitlab::group/subgroup/subsubgroup/project/-/subdir@ref
 ```
 
 ### Packages in git repositories (`git::`)
@@ -298,6 +305,9 @@ Full syntax:
 If `<detail>` is missing, then the latest commit of the _default_
 branch is used.
 
+`git::` supports git submodules, see the `git-submodules` configuration
+entry.
+
 Examples:
 ```
 git::https://github.com/r-lib/crayon

diff --git a/tools/doc/pkg-refs.md b/tools/doc/pkg-refs.md
@@ -256,25 +256,32 @@ A GitHub remote string can also be used instead of an URL, for example:
 
 Packages from a GitLab repository. Full syntax:
 
-\if{html}{\out{<div class="sourceCode">}}\preformatted{[<package>=][github::]<username>/<repository>[/<subdir>][<detail>]
+\if{html}{\out{<div class="sourceCode">}}\preformatted{[<package>=][github::]<project-path>/<repository>[/-/<subdir>][<detail>]
 }\if{html}{\out{</div>}}
 \itemize{
 \item \verb{<package>} is the name of the package. If this is missing, then
 the name of the repository is used.
-\item \verb{<username>} is a GitLab username or group name.
-\item \verb{<repository>} is the name of the repository.
+\item \verb{<project-path>} is a typically the GitLab username or group name, but
+it may contain subgroups.
+\item \verb{<repository>} is the name of the repository, or the project in GitLab
+terminology.
 \item \verb{<subdir>} optional subdirectory, if the package is within a
-subdirectory in the repository.
+subdirectory in the repository. Note that for GitLab, this must come
+after a \verb{/-} prefix, to be able to distinguish it from subgroups.
 \item \verb{<detail>} may specify a git branch, tag or (prefix of) a commit hash.
 }
 
 If \verb{<detail>} is missing, then the latest commit of the \emph{default}
 branch is used.
 
+\verb{gitlab::} supports git submodules, see the \code{git-submodules} configuration
+entry.
+
 Examples:
 
 \if{html}{\out{<div class="sourceCode">}}\preformatted{gitlab::gaborcsardi/cli
 gitlab::r-hub/filelock@main
+gitlab::group/subgroup/subsubgroup/project/-/subdir@ref
 }\if{html}{\out{</div>}}
 }
 
@@ -296,6 +303,9 @@ a git branch, tag or (prefix of) a commit hash: \verb{@<commitish>}.
 If \verb{<detail>} is missing, then the latest commit of the \emph{default}
 branch is used.
 
+\verb{git::} supports git submodules, see the \code{git-submodules} configuration
+entry.
+
 Examples:
 
 \if{html}{\out{<div class="sourceCode">}}\preformatted{git::https://github.com/r-lib/crayon