From 4a93202fc8cfe42b83e7ff21a67ecdbcbd15cb48 Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@collabora.com>
Date: Sun, 16 Jan 2022 12:38:25 +0000
Subject: [PATCH] run, override: Clarify the effect of --nofilesystem

There are two reasonable interpretations for --nofilesystem=home:
either it revokes a previous --filesystem=home (as in Flatpak 1.12.2 and
older versions), or it completely forbids access to the home directory
(as in Flatpak 1.12.3). Clarify the man pages to indicate that it only
revokes a previous --filesystem=home. This will hopefully reduce
mismatches between the design and what users expect to happen, as
in flatpak#4654.

A subsequent commit will introduce a way to get the Flatpak 1.12.3
behaviour in a way that is more backwards-compatible with Flatpak 1.12.2
and older versions.

Signed-off-by: Simon McVittie <smcv@collabora.com>
(cherry picked from commit 7bbeed2b87b84d6d94006e25418b7f89a7784fdb)
---
 doc/flatpak-override.xml | 28 +++++++++++++++++++++++-----
 doc/flatpak-run.xml      | 26 +++++++++++++++++++++-----
 2 files changed, 44 insertions(+), 10 deletions(-)

diff --git a/doc/flatpak-override.xml b/doc/flatpak-override.xml
index e2768a42..05c4a800 100644
--- a/doc/flatpak-override.xml
+++ b/doc/flatpak-override.xml
@@ -223,13 +223,31 @@
                 <term><option>--nofilesystem=FILESYSTEM</option></term>
 
                 <listitem><para>
-                    Remove access to the specified subset of the filesystem from
-                    the application. This overrides to the Context section from the
+                    Undo the effect of a previous
+                    <option>--filesystem=</option><arg choice="plain">FILESYSTEM</arg>
+                    in the app's manifest or a lower-precedence layer of
+                    overrides, and/or remove a previous
+                    <option>--filesystem=</option><arg choice="plain">FILESYSTEM</arg>
+                    from this layer of overrides.
+                    This overrides the Context section of the
                     application metadata.
-                    <arg choice="plain">FILESYSTEM</arg> can be one of: home, host, host-os, host-etc, xdg-desktop, xdg-documents, xdg-download,
-                    xdg-music, xdg-pictures, xdg-public-share, xdg-templates, xdg-videos,
-                    an absolute path, or a homedir-relative path like ~/dir.
+                    <arg choice="plain">FILESYSTEM</arg> can take the same
+                    values as for <option>--filesystem</option>, but the
+                    <arg choice="plain">:ro</arg> and
+                    <arg choice="plain">:create</arg> suffixes are not
+                    used here.
                     This option can be used multiple times.
+                </para><para>
+                    This option does not prevent access to a more
+                    narrowly-scoped <option>--filesystem</option>.
+                    For example, if an application has the equivalent of
+                    <option>--filesystem=xdg-config/MyApp</option> in
+                    its manifest or as a system-wide override, and
+                    <literal>flatpak override --user --nofilesystem=home</literal>
+                    as a per-user override, then it will be prevented from
+                    accessing most of the home directory, but it will still
+                    be allowed to access
+                    <filename>$XDG_CONFIG_HOME/MyApp</filename>.
                 </para></listitem>
             </varlistentry>
 
diff --git a/doc/flatpak-run.xml b/doc/flatpak-run.xml
index a9c2c947..69df02c9 100644
--- a/doc/flatpak-run.xml
+++ b/doc/flatpak-run.xml
@@ -366,13 +366,29 @@
                 <term><option>--nofilesystem=FILESYSTEM</option></term>
 
                 <listitem><para>
-                    Remove access to the specified subset of the filesystem from
-                    the application. This overrides to the Context section from the
+                    Undo the effect of a previous
+                    <option>--filesystem=</option><arg choice="plain">FILESYSTEM</arg>
+                    in the app's manifest and/or the overrides set up with
+                    <citerefentry><refentrytitle>flatpak-override</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+                    This overrides the Context section of the
                     application metadata.
-                    <arg choice="plain">FILESYSTEM</arg> can be one of: home, host, host-os, host-etc, xdg-desktop, xdg-documents, xdg-download,
-                    xdg-music, xdg-pictures, xdg-public-share, xdg-templates, xdg-videos,
-                    an absolute path, or a homedir-relative path like ~/dir.
+                    <arg choice="plain">FILESYSTEM</arg> can take the same
+                    values as for <option>--filesystem</option>, but the
+                    <arg choice="plain">:ro</arg> and
+                    <arg choice="plain">:create</arg> suffixes are not
+                    used here.
                     This option can be used multiple times.
+                </para><para>
+                    This option does not prevent access to a more
+                    narrowly-scoped <option>--filesystem</option>.
+                    For example, if an application has the equivalent of
+                    <option>--filesystem=xdg-config/MyApp</option> in
+                    its manifest or as a system-wide override, and
+                    <literal>flatpak override --user --nofilesystem=home</literal>
+                    as a per-user override, then it will be prevented from
+                    accessing most of the home directory, but it will still
+                    be allowed to access
+                    <filename>$XDG_CONFIG_HOME/MyApp</filename>.
                 </para></listitem>
             </varlistentry>