From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by lists.proxmox.com (Postfix) with ESMTPS id 8CB7A669A6 for ; Tue, 28 Jul 2020 09:24:11 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 7AAC521C72 for ; Tue, 28 Jul 2020 09:24:11 +0200 (CEST) Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com [212.186.127.180]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by firstgate.proxmox.com (Proxmox) with ESMTPS id CA65F21C69 for ; Tue, 28 Jul 2020 09:24:10 +0200 (CEST) Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1]) by proxmox-new.maurer-it.com (Proxmox) with ESMTP id 9811543212 for ; Tue, 28 Jul 2020 09:24:10 +0200 (CEST) From: Dylan Whyte To: pbs-devel@lists.proxmox.com Date: Tue, 28 Jul 2020 09:24:04 +0200 Message-Id: <20200728072404.15187-1-d.whyte@proxmox.com> X-Mailer: git-send-email 2.20.1 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-SPAM-LEVEL: Spam detection results: 0 KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Subject: [pbs-devel] [PATCH pbs-docs] docs: pxar create: update docs to match current behavior X-BeenThere: pbs-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox Backup Server development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 28 Jul 2020 07:24:11 -0000 This removes parts of the previous explanation of the tool that are no longer correct, and adds an explanation of '--exclude' parameter, instead. Adds more clarity to the command, by use of '/path/to/source' to signify source directory. Specify that the pattern matching style of the exclude parameter is that of gitignore's syntax. --- docs/pxar/description.rst | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/pxar/description.rst b/docs/pxar/description.rst index 82b15fd9..f305ec07 100644 --- a/docs/pxar/description.rst +++ b/docs/pxar/description.rst @@ -18,7 +18,7 @@ Run the following command to create an archive of a folder named ``source``: .. code-block:: console - # pxar create archive.pxar source + # pxar create archive.pxar /path/to/source This will create a new archive called ``archive.pxar`` with the contents of the ``source`` folder. @@ -35,35 +35,34 @@ To alter this behavior and follow device boundaries, use the ``--all-file-systems`` flag. It is possible to exclude certain files and/or folders from the archive by -passing glob match patterns as additional parameters. Whenever a file is matched -by one of the patterns, you will get a warning stating that this file is skipped -and therefore not included in the archive. +passing the ``--exclude`` parameter with ``gitignore``\-style match patterns. For example, you can exclude all files ending in ``.txt`` from the archive by running: .. code-block:: console - # pxar create archive.pxar source '**/*.txt' + # pxar create archive.pxar /path/to/source --exclude '**/*.txt' Be aware that the shell itself will try to expand all of the glob patterns before invoking ``pxar``. In order to avoid this, all globs have to be quoted correctly. - -It is possible to pass a list of match patterns to fulfill more complex -file exclusion/inclusion behavior, although it is recommended to use the + +It is possible to pass the ``--exclude`` parameter multiple times, in order to +match more than one pattern. This allows you to use more complex +file exclusion/inclusion behavior. However, it is recommended to use ``.pxarexclude`` files instead for such cases. For example you might want to exclude all ``.txt`` files except for a specific one from the archive. This is achieved via the negated match pattern, prefixed by ``!``. -All the glob pattern are relative to the ``source`` directory. +All the glob patterns are relative to the ``source`` directory. .. code-block:: console - # pxar create archive.pxar source '**/*.txt' '!/folder/file.txt' + # pxar create archive.pxar /path/to/source --exclude '**/*.txt' --exclude '!/folder/file.txt' -.. NOTE:: The order of the glob match patterns matters as later ones win over +.. NOTE:: The order of the glob match patterns matters as later ones override previous ones. Permutations of the same patterns lead to different results. ``pxar`` will store the list of glob match patterns passed as parameters via the -- 2.20.1