Send patches - preferably formatted by git format-patch - to patches at archlinux32 dot org.
summaryrefslogtreecommitdiff
path: root/doc/man/pkgctl-version-setup.1.asciidoc
diff options
context:
space:
mode:
authorJelle van der Waa <jelle@archlinux.org>2024-01-21 13:25:57 +0100
committerChristian Heusel <christian@heusel.eu>2024-03-23 23:57:45 +0100
commit81f5e7b3b3f6e2687ebca03e212e0e7bc2da171f (patch)
treed84fce3878db9e52a8628e359e6d8882ebb22f78 /doc/man/pkgctl-version-setup.1.asciidoc
parent01b6b0849ed098d4d3d8db3591443db3df6aa11b (diff)
feat(version): add command to automatically detect and setup nvchecker
Introduce a new version subcommand `setup` which does a best effort to generate the most minimal required .nvchecker.toml file for specific sources. It supports a wide range of common sources like: - Git, GitHub, GitLab, Hackage, NPM, PyPI, RubyGems, CPAN, crates.io The creation logic is based on matching a domain for a source which is something predictable and then simply passes an array of the url parts for every source creator to extract the useful bits out of the url array. Component: pkgctl version setup Co-authored-by: Levente Polyak <anthraxx@archlinux.org> Signed-off-by: Jelle van der Waa <jelle@archlinux.org>
Diffstat (limited to 'doc/man/pkgctl-version-setup.1.asciidoc')
-rw-r--r--doc/man/pkgctl-version-setup.1.asciidoc120
1 files changed, 120 insertions, 0 deletions
diff --git a/doc/man/pkgctl-version-setup.1.asciidoc b/doc/man/pkgctl-version-setup.1.asciidoc
new file mode 100644
index 0000000..81ef008
--- /dev/null
+++ b/doc/man/pkgctl-version-setup.1.asciidoc
@@ -0,0 +1,120 @@
+pkgctl-version-setup(1)
+=======================
+
+Name
+----
+pkgctl-version-setup - Automatically detect and setup a basic nvchecker config
+
+Synopsis
+--------
+pkgctl version setup [OPTIONS] [PKGBASE...]
+
+Description
+-----------
+
+This subcommand automates the creation of a basic nvchecker(1) configuration
+file by analyzing the source array specified in the PKGBUILD(1) file of a
+package. This command intelligently detects various platforms and APIs (e.g.,
+GitHub, GitLab, PyPI) used by the package sources and generates a corresponding
+`.nvchecker.toml` configuration based on its best guess.
+
+This is particularly useful for initializing nvchecker(1) settings for a
+package without manually crafting the `.nvchecker.toml` file. It simplifies the
+process of setting up version checks, especially when transitioning a package's
+monitoring from one source platform to another or starting version checks for a
+new package.
+
+If no `PKGBASE` is specified, the command defaults to using the current working
+directory.
+
+To obtain a list of supported sources and their expected URL formats, please
+consult the sources section.
+
+Options
+-------
+
+*-f, --force*::
+ Overwrite existing nvchecker(1) configuration
+
+*--prefer-platform-api*::
+ Prefer platform specific GitHub/GitLab API over git for complex cases
+
+*--url* 'URL'::
+ Derive check target from the given URL instead of the source array entries
+
+
+*--no-check*::
+ Do not run pkgctl-version-check(1) after setup
+
+*-h, --help*::
+ Show a help text
+
+Sources
+-------
+
+Here are the currently supported platforms and sources, along with examples of
+URL formats that enable their automatic detection as specific source types:
+
+*Git*::
+ * https://github.com/example/project
+ * https://gitlab.com/example/group/project
+ * git://git.foobar.org/example
+ * git+https://git.foobar.org/example
+
+*GitHub*::
+ * https://github.com/example/project
+ * https://github.com/example/project/archive/v1.0/project-v1.0.tar.gz
+
+*GitLab*::
+ * https://gitlab.com/example/group/project
+ * https://gitlab.archlinux.org/archlinux/devtools.git
+ * https://gitlab.archlinux.org/archlinux/devtools/-/releases/v1.1.0/downloads/devtools-v1.1.0.tar.gz
+
+*Hackage*::
+ * https://hackage.haskell.org/package/xmonad
+ * https://hackage.haskell.org/package/xmonad-0.18.0/xmonad-0.18.0.tar.gz
+ * https://hackage.haskell.org/packages/archive/xmonad/0.18.0/xmonad-0.18.0.tar.gz
+
+*NPM*::
+ * https://registry.npmjs.org/node-gyp/-/node-gyp-10.0.1.tgz
+ * https://www.npmjs.com/package/node-gyp
+
+*PyPI*::
+ * https://pypi.io/packages/source/p/pyflakes
+ * https://pypi.org/packages/source/b/bleach
+ * https://files.pythonhosted.org/packages/source/p/pyflakes
+ * https://pypi.org/project/SQLAlchemy/
+
+*RubyGems*::
+ * https://rubygems.org/downloads/diff-lcs-1.5.1.gem
+ * https://rubygems.org/gems/diff-lcs
+
+*CPAN*::
+ * https://search.cpan.org/CPAN/authors/id/C/CO/COSIMO/Locale-PO-0.27.tar.gz
+ * https://cpan.metacpan.org/authors/id/C/CO/COSIMO/Locale-PO-0.27.tar.gz
+
+*crates.io*::
+ * https://static.crates.io/crates/shotgun/shotgun-1.0.crate
+ * https://crates.io/api/v1/crates/shotgun/1.0/download
+ * https://crates.io/crates/git-smash
+
+Examples
+--------
+
+*pkgctl version setup*::
+ Detects the source from the current directory's PKGBUILD(1) and
+ sets up a basic `.nvchecker.toml`.
+
+*pkgctl version setup --url https://github.com/example/project*::
+ Generates an `.nvchecker.toml` for the current PKGBUILD(1) but
+ overrides the source URL with the specified GitHub project.
+
+See Also
+--------
+
+pkgctl-version(1)
+pkgctl-version-check(1)
+nvchecker(1)
+PKGBUILD(5)
+
+include::include/footer.asciidoc[]