Skip to content

tips-and-tricks: Document masking in more detail #583

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 13, 2025
Merged

tips-and-tricks: Document masking in more detail #583

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b76a07f
tips-and-tricks: Document masking in more detail
bbhtt Mar 13, 2025
0965738
Update po files
bbhtt Mar 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 36 additions & 4 deletions docs/tips-and-tricks.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,12 +44,44 @@ Then you deploy the commit::
.. note::

The example here uses ``sudo`` for system installations because, unlike normal updates, downgrades are considered a privileged action. If the application is installed per-user you would run it as that user.

If you have Flatpak 1.5.0 or later, you can also prevent the app from being
included in updates (either manual or automatic)::

$ flatpak mask org.gnome.Recipes
Masking
--------

Flatpak 1.5.0 or later allows to mask a ref to prevent it from being
automatically updated or installed.

If the Flatpak remote is configured in user location,
``flatpak mask --user`` needs to be used otherwise it defaults to
system location. ``flatpak remote-list`` can be used to find the
location of the Flatpak remote.

To list the currently masked patterns::

# System
$ flatpak mask

# User
$ flatpak mask --user

To mask a ref pattern::

# System
$ flatpak mask org.example.brokenapp

# User
$ flatpak mask --user org.example.brokenapp

# Mask only the beta branch of the ref
$ flatpak mask org.example.brokenapp//beta

To remove a masked pattern::

# System
$ flatpak mask --remove org.example.brokenapp

# User
$ flatpak mask --user --remove org.example.brokenapp

Bisecting regressions in application builds
-------------------------------------------
Expand Down
91 changes: 61 additions & 30 deletions po/de/LC_MESSAGES/tips-and-tricks.po
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,14 @@ msgid ""
msgstr ""
"Project-Id-Version: Flatpak \n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2023-01-07 16:26-0600\n"
"POT-Creation-Date: 2025-03-13 09:53+0530\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <[email protected]>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.10.3\n"
"Generated-By: Babel 2.17.0\n"

#: ../../tips-and-tricks.rst:2
msgid "Tips and Tricks"
Expand Down Expand Up @@ -80,92 +80,116 @@ msgid ""
"application is installed per-user you would run it as that user."
msgstr ""

#: ../../tips-and-tricks.rst:48
#: ../../tips-and-tricks.rst:49
msgid "Masking"
msgstr ""

#: ../../tips-and-tricks.rst:51
msgid ""
"Flatpak 1.5.0 or later allows to mask a ref to prevent it from being "
"automatically updated or installed."
msgstr ""

#: ../../tips-and-tricks.rst:54
msgid ""
"If you have Flatpak 1.5.0 or later, you can also prevent the app from "
"being included in updates (either manual or automatic)::"
"If the Flatpak remote is configured in user location, ``flatpak mask "
"--user`` needs to be used otherwise it defaults to system location. "
"``flatpak remote-list`` can be used to find the location of the Flatpak "
"remote."
msgstr ""

#: ../../tips-and-tricks.rst:59
msgid "To list the currently masked patterns::"
msgstr ""

#: ../../tips-and-tricks.rst:67
msgid "To mask a ref pattern::"
msgstr ""

#: ../../tips-and-tricks.rst:78
msgid "To remove a masked pattern::"
msgstr ""

#: ../../tips-and-tricks.rst:55
#: ../../tips-and-tricks.rst:87
msgid "Bisecting regressions in application builds"
msgstr ""

#: ../../tips-and-tricks.rst:57
#: ../../tips-and-tricks.rst:89
msgid ""
"In case the newest builds of an application introduce regressions, you "
"can use ``flatpak-bisect`` to discover which commit introduced the "
"regression. It works just like ``git bisect``."
msgstr ""

#: ../../tips-and-tricks.rst:61
#: ../../tips-and-tricks.rst:93
msgid ""
"In case your distribution doesn't install the ``flatpak-bisect`` utility,"
" you can find it distributed alongside the Flatpak source code, in "
"https://github.com/flatpak/flatpak/blob/main/scripts/flatpak-bisect"
msgstr ""

#: ../../tips-and-tricks.rst:65
#: ../../tips-and-tricks.rst:97
msgid "First you update the application and get its history::"
msgstr ""

#: ../../tips-and-tricks.rst:69
#: ../../tips-and-tricks.rst:101
msgid "Then, you should set the current commit as the first bad commit::"
msgstr ""

#: ../../tips-and-tricks.rst:73
#: ../../tips-and-tricks.rst:105
msgid ""
"Now you need to find the hash of the first known good commit. For that, "
"you can see the build history by running::"
msgstr ""

#: ../../tips-and-tricks.rst:78
#: ../../tips-and-tricks.rst:110
msgid "To start bisecting, checkout the first known good commit you find::"
msgstr ""

#: ../../tips-and-tricks.rst:82
#: ../../tips-and-tricks.rst:114
msgid ""
"After setting the bad commit and the first known good commit, you can "
"launch the application to verify if the current commit in the bisecting "
"session is a good or a bad one."
msgstr ""

#: ../../tips-and-tricks.rst:86
#: ../../tips-and-tricks.rst:118
msgid "To mark a commit as good or bad, run::"
msgstr ""

#: ../../tips-and-tricks.rst:90
#: ../../tips-and-tricks.rst:122
msgid "Or::"
msgstr ""

#: ../../tips-and-tricks.rst:94
#: ../../tips-and-tricks.rst:126
msgid "``flatpak-bisect`` will inform you when the first bad commit is found."
msgstr ""

#: ../../tips-and-tricks.rst:97
#: ../../tips-and-tricks.rst:129
msgid "Adding a custom installation"
msgstr ""

#: ../../tips-and-tricks.rst:99
#: ../../tips-and-tricks.rst:131
msgid ""
"By default Flatpak installs apps system-wide, and can also be made to "
"install per-user with the ``--user`` option accepted by most commands. A "
"third option is to set up a custom installation, which could be stored on"
" an external hard drive."
msgstr ""

#: ../../tips-and-tricks.rst:104
#: ../../tips-and-tricks.rst:136
msgid "First ensure that the config directory exists::"
msgstr ""

#: ../../tips-and-tricks.rst:108
#: ../../tips-and-tricks.rst:140
msgid "Then open a file in that directory as root::"
msgstr ""

#: ../../tips-and-tricks.rst:112
#: ../../tips-and-tricks.rst:144
msgid "And write something like this::"
msgstr ""

#: ../../tips-and-tricks.rst:119
#: ../../tips-and-tricks.rst:151
msgid ""
"See `flatpak-installation(5) <https://docs.flatpak.org/en/latest/flatpak-"
"command-reference.html#flatpak-installation>`_ for the full format "
Expand All @@ -174,35 +198,35 @@ msgid ""
"``flatpak`` directory so the path specified by ``Path=`` exists."
msgstr ""

#: ../../tips-and-tricks.rst:125
#: ../../tips-and-tricks.rst:157
msgid "Then you can add a remote using a command like::"
msgstr ""

#: ../../tips-and-tricks.rst:129
#: ../../tips-and-tricks.rst:161
msgid "And install to it with::"
msgstr ""

#: ../../tips-and-tricks.rst:135
#: ../../tips-and-tricks.rst:167
msgid ""
"If your custom installation is the only one with the remote you're "
"installing from, ``--installation`` can be omitted."
msgstr ""

#: ../../tips-and-tricks.rst:138
#: ../../tips-and-tricks.rst:170
msgid "And run apps from it with::"
msgstr ""

#: ../../tips-and-tricks.rst:144
#: ../../tips-and-tricks.rst:176
msgid ""
"If your custom installation is the only one with the app you're running, "
"``--installation`` can be omitted."
msgstr ""

#: ../../tips-and-tricks.rst:148
#: ../../tips-and-tricks.rst:180
msgid "Configuring resource limits for apps"
msgstr ""

#: ../../tips-and-tricks.rst:150
#: ../../tips-and-tricks.rst:182
msgid ""
"When systemd is available, Flatpak tries to put app processes in a scope "
"such as ``app-flatpak-com.brave.Browser-*.scope`` (in the case of Brave),"
Expand All @@ -211,7 +235,7 @@ msgid ""
"com.brave.Browser-.scope.d/memory.conf`` with contents like::"
msgstr ""

#: ../../tips-and-tricks.rst:159
#: ../../tips-and-tricks.rst:191
msgid ""
"Then after a ``systemctl --user daemon-reload``, those ``systemd"
".resource-control(5)`` parameters will apply to all instances of that "
Expand Down Expand Up @@ -240,3 +264,10 @@ msgstr ""
#~ "``Path=`` exists."
#~ msgstr ""

#~ msgid ""
#~ "If you have Flatpak 1.5.0 or "
#~ "later, you can also prevent the "
#~ "app from being included in updates "
#~ "(either manual or automatic)::"
#~ msgstr ""

Loading