feature: pack folder

2026-09-10 13:38:47 +02:00
parent 6998242b58
commit 89bcad5cdc
9 changed files with 978 additions and 16 deletions
@@ -83,3 +83,47 @@ The optional arguments influence the manner of packing::
                            to exclude.

 For more information see the chapter :ref:`packing`.
+
+
+Pack folder
+-----------
+
+The ``bat pack-folder`` command scans a directory tree, collects every
+``.blend`` file in it, traces the dependencies of all of them, and packs the
+whole lot into a single target. Assets used by more than one blend file are
+only stored once::
+
+    bat pack-folder [-h] -t TARGET [-p PROJECT] [-n] [-e [EXCLUDE ...]] [-c]
+                    [-r] [--keep-hierarchy] [--latest-only] [--follow-symlinks]
+                    [--ignore-dir [GLOB ...]] [--no-validate] folder
+
+For example, to zip up a project's work directory::
+
+    bat pack-folder /z/projects/garde_a_vue/work -t /tmp/gav_work.zip --latest-only
+
+Backup files (``.blend1``, ``.blend2``, …) are never packed. By default the
+scanned folder also acts as the project root, so the pack mirrors the folder's
+own structure and assets referenced from outside it end up in
+``_outside_project``. Use ``--keep-hierarchy`` to mirror the full filesystem
+paths instead.
+
+The options specific to this subcommand are::
+
+      -t TARGET, --target TARGET
+                            Target directory or ZIP file (required).
+      --latest-only         Of every 'name_vNNN.blend' version series in a
+                            directory, only pack the highest version. Variants
+                            like 'name_vNNN_light.blend' form their own series;
+                            files without a version are always packed.
+      --follow-symlinks     Descend into symlinked directories while scanning.
+                            Already-visited directories are skipped, so symlink
+                            loops are safe.
+      --ignore-dir [GLOB ...]
+                            Globs of directory names to skip while scanning
+                            (default: .* __pycache__).
+      --no-validate         Don't check that each '.blend' file really is a
+                            blend file. Faster, but a non-blend file will abort
+                            the pack.
+
+The other options (``-p``, ``-n``, ``-e``, ``-c``, ``-r``, ``--keep-hierarchy``)
+mean the same as for ``bat pack``.