From f6d1a064b9046bcdf67e7bee95cc5c40b440f18d Mon Sep 17 00:00:00 2001 From: Alexander Larsson Date: Tue, 13 Dec 2016 11:18:16 +0100 Subject: [PATCH] Clean up docs/help for install and remote-add This makes it easier how the different variants like --from and --bundle work. Fixes https://github.com/flatpak/flatpak/issues/438 and https://github.com/flatpak/flatpak/issues/439 --- app/flatpak-builtins-install.c | 8 ++--- app/flatpak-main.c | 2 +- doc/flatpak-install.xml | 65 ++++++++++++++++++++-------------- doc/flatpak-remote-add.xml | 29 ++++++++++----- 4 files changed, 65 insertions(+), 39 deletions(-) diff --git a/app/flatpak-builtins-install.c b/app/flatpak-builtins-install.c index 2885c7e0..6ccf467b 100644 --- a/app/flatpak-builtins-install.c +++ b/app/flatpak-builtins-install.c @@ -59,9 +59,9 @@ static GOptionEntry options[] = { { "no-deps", 0, 0, G_OPTION_ARG_NONE, &opt_no_deps, N_("Don't verify/install runtime dependencies"), NULL }, { "runtime", 0, 0, G_OPTION_ARG_NONE, &opt_runtime, N_("Look for runtime with the specified name"), NULL }, { "app", 0, 0, G_OPTION_ARG_NONE, &opt_app, N_("Look for app with the specified name"), NULL }, - { "bundle", 0, 0, G_OPTION_ARG_NONE, &opt_bundle, N_("Install from local bundle file"), NULL }, - { "from", 0, 0, G_OPTION_ARG_NONE, &opt_from, N_("Load options from file or uri"), NULL }, - { "oci", 0, 0, G_OPTION_ARG_NONE, &opt_oci, N_("Install from oci image"), NULL }, + { "bundle", 0, 0, G_OPTION_ARG_NONE, &opt_bundle, N_("Assume LOCATION is a .flatpak single-file bundle"), NULL }, + { "from", 0, 0, G_OPTION_ARG_NONE, &opt_from, N_("Assume LOCATION is a .flatpakref application description"), NULL }, + { "oci", 0, 0, G_OPTION_ARG_NONE, &opt_oci, N_("Assume LOCATION is an oci registry"), NULL }, { "gpg-file", 0, 0, G_OPTION_ARG_FILENAME_ARRAY, &opt_gpg_file, N_("Check bundle signatures with GPG key from FILE (- for stdin)"), N_("FILE") }, { "subpath", 0, 0, G_OPTION_ARG_FILENAME_ARRAY, &opt_subpaths, N_("Only install this subpath"), N_("PATH") }, { NULL } @@ -366,7 +366,7 @@ flatpak_builtin_install (int argc, char **argv, GCancellable *cancellable, GErro FlatpakKinds kinds; g_autoptr(FlatpakTransaction) transaction = NULL; - context = g_option_context_new (_("REMOTE REF... - Install applications or runtimes")); + context = g_option_context_new (_("LOCATION/REMOTE [REF...] - Install applications or runtimes")); g_option_context_set_translation_domain (context, GETTEXT_PACKAGE); if (!flatpak_option_context_parse (context, options, &argc, &argv, 0, &dir, cancellable, error)) diff --git a/app/flatpak-main.c b/app/flatpak-main.c index abcb79c2..da011794 100644 --- a/app/flatpak-main.c +++ b/app/flatpak-main.c @@ -55,7 +55,7 @@ typedef struct static FlatpakCommand commands[] = { /* translators: please keep the leading space */ { N_(" Manage installed apps and runtimes") }, - { "install", N_("Install an application or runtime from a remote"), flatpak_builtin_install, flatpak_complete_install }, + { "install", N_("Install an application or runtime"), flatpak_builtin_install, flatpak_complete_install }, { "update", N_("Update an installed application or runtime"), flatpak_builtin_update, flatpak_complete_update }, { "uninstall", N_("Uninstall an installed application or runtime"), flatpak_builtin_uninstall, flatpak_complete_uninstall }, { "list", N_("List installed apps and/or runtimes"), flatpak_builtin_list, flatpak_complete_list }, diff --git a/doc/flatpak-install.xml b/doc/flatpak-install.xml index 10797e39..f5b782ae 100644 --- a/doc/flatpak-install.xml +++ b/doc/flatpak-install.xml @@ -29,29 +29,33 @@ + Install from a configured remote: flatpak install OPTION - REMOTE + REMOTE-NAME REF + Install from a .flatpakref file: flatpak install OPTION - - --bundle - --from - + --from + LOCATION + + Install from a .flatpak bundle: + + flatpak install + OPTION + --bundle FILENAME + Install from an OCI registry: - flatpak install --oci + flatpak install OPTION - - --bundle - --from - - REGISTRYURI + --oci + LOCATION TAG @@ -60,12 +64,13 @@ Description - Installs an application or runtime. REMOTE must name - an existing remote and REF is a reference to the - application or runtime to install. + Installs an application or runtime. The primary way to + install is to specify a REMOTE + name as the source and one ore more REFs to specify the + application or runtime to install. - Each REF arguments is a full or partial indentifier in the + Each REF argument is a full or partial indentifier in the flatpak ref format, which looks like "(app|runtime)/ID/ARCH/BRANCH". All elements except ID are optional and can be left out, including the slashes, so most of the time you need only specify ID. Any part left out will be matched @@ -77,6 +82,14 @@ the specified REMOTE, but you can limit this by using the --app or --runtime option, or by supplying the initial element in the REF. + + The alternative form of the command (--from, + --bundle or --oci) allows you to + install directly from a source such as a .flatpak + single-file bundle, a .flatpakref app description or an + OCI registry. The options are optional if the first + argument have the right extension. + Note that flatpak allows one to have multiple branches of an application and runtimes installed and used at the same time. However, only version of an application one can be current, @@ -88,12 +101,6 @@ Unless overridden with the --user option, this command creates a system-wide installation. - - The alternative form of the command installs an application from a - single-file bundle or a flatpakref file instead of a configured remote. - Bundles can be created with the flatpak build-bundle command, flatpakref - files are simple references to a remote repo for an application. - @@ -116,8 +123,8 @@ - Install from a bundle file instead - of a configured remote. + Assume LOCATION is a .flatpak single-bundle file. + This is optional if the arguments ends with .flatpak. @@ -125,8 +132,8 @@ - Install from a flatpakref file instead - of a configured remote. + Assume LOCATION is a .flatpakref file containing the details of the app to be installed. + This is optional if the arguments ends with .flatpakref. @@ -249,7 +256,13 @@ Examples - $ flatpak --user install test-repo org.gnome.GEdit + $ flatpak -install gnome org.gnome.gedit2 + + + $ flatpak --user install gnome org.gnome.gedit//3.22 + + + $ flatpak --user install https://sdk.gnome.org/gedit.flatpakref diff --git a/doc/flatpak-remote-add.xml b/doc/flatpak-remote-add.xml index c863ca6b..05eced50 100644 --- a/doc/flatpak-remote-add.xml +++ b/doc/flatpak-remote-add.xml @@ -29,6 +29,15 @@ + Add from a .flatpakrepo file: + + flatpak remote-add + OPTION + --from + NAME + LOCATION + + Manually specify repo uri and options: flatpak remote-add OPTION @@ -41,18 +50,18 @@ Description - Adds a remote repository to the flatpak repository configuration. - NAME is the name for the new remote, and - LOCATION is the url or pathname for the repository. + Adds a remote repository to the flatpak repository + configuration. NAME is the name for the new + remote, and LOCATION is a url or pathname. The + LOCATION is either a flatpak repository, or a + .flatpakrepo file which describes a repository. In the + former case you may also have to specify extra options, + such as the gpg key for the repo. Unless overridden with the --user option, this command changes the system-wide configuration. - - The alternative form of the command adds a remote from a flatpakrepo - file. - @@ -75,7 +84,8 @@ - Add from a flatpakrepo file (local or http uri) instead of from commandline arguments. This means the LOCATION argument specifies the filename/uri of a flatpakref rather than a repo url. + Assume the URI is a .flatpakrepo file rather than the repository itself. This is enabled + by default if the extension is .flatpakrepo, so generally you don't need this option. @@ -203,6 +213,9 @@ Examples + + $ flatpak remote-add gnome https://sdk.gnome.org/gnome.flatpakrepo + $ flatpak --user remote-add --no-gpg-verify test-repo https://people.gnome.org/~alexl/gnome-sdk/repo/