extract

8BitSafe-cli [common options] archive extract [options] [REPO::ARCHIVE] [PATH...]

positional arguments	description
REPO::ARCHIVE	archive to extract
PATH(S)	paths to extract (glob supported)

optional arguments	description	default	allowed
-e,--exclude <patterns>	exclude pattern(s)	-	paths or glob patterns
--no-cache	Do not use/update file cache	-
--no-obj-cache	Do not use/update object cache	-
--no-check-free-space	Do not check free disk space before extract	-
--ratelimit <limitString>	Download rate limit	-	limitString
--tar <path>	Places all extracted files inside a tar at the given path (optional compression)	-
--map [<sourcePrefix>,<target>]	Map archive paths to new locations during extract	-

Description

Extracts the contents of an archive to disk or tar (compression supported).

tip

When you create an archive you pass either absolute or relative paths, the same absolute or relative paths are used when extracting.

If you used relative paths then files are extracted relative to the working directory of the extract operation

Paths and exclusions

By default the entire archive is extracted but a subset of files and directories can be selected by passing paths and/or exclusions.

Both paths and exclusions support glob patterns.

Examples

info

For example if you run archive create with the following paths:

Windows

8BitSafe-cli.exe archive create D:\repo::initial C:\User\Tom\Docs D:\games "G:\My Pictures"

Extract top level files ending in .doc from C:\User\Tom\ but skip any file that contains the word personal

8BitSafe-cli.exe archive extract -e "*personal*" D:\repo::initial C:\User\Tom\*.doc 

Extract files ending in either .jpg, .png or .gif from G:\My Pictures\ excluding any files in G:\My Pictures\holiday\

8BitSafe-cli.exe archive extract -e "G:\My Pictures\holiday\**" D:\repo::initial "G:\My Pictures\**.{jpg,png,gif}" 

Unix

8BitSafe-cli archive create /mnt/repo::initial /home/Tom/Docs /mnt/games "/nfs/My Pictures"

Extract top level files ending in .doc from /home/Tom/Docs/ but skip any file that contains the word personal

8BitSafe-cli archive extract -e "*personal*" /mnt/repo::initial /home/Tom/Docs*.doc 

Extract files ending in either .jpg, .png or .gif from /nfs/My Pictures/ excluding any files in /nfs/My Pictures/holiday/

8BitSafe-cli archive extract -e "/nfs/My Pictures/holiday/**" /mnt/repo::initial "/nfs/My Pictures/**.{jpg,png,gif}" 

Extract rate

You can limit the speed at which data is pulled from the repo during extract this works for all store types, even local disk.

Examples

info

Windows

8BitSafe-cli.exe archive extract --ratelimit 15Mbps D:\backups\repo::archive1

set BS_REPO="D:\backups\repo"
8BitSafe-cli.exe archive extract --ratelimit 100MBps ::archive1
8BitSafe-cli.exe archive extract --ratelimit 50MiB ::archive1

Unix

8BitSafe-cli archive extract --ratelimit 15Mbps /mnt/backups/repo::archive1

export BS_REPO="/mnt/backups/repo"
8BitSafe-cli archive extract --ratelimit 100MBps ::archive1
8BitSafe-cli archive extract --ratelimit 50MiB ::archive1

Tar

Instead of writing all the extracted files to the filesystem the files are all placed inside a tar.

This works on both Windows and Linux.

Examples

info

Windows

8BitSafe-cli.exe archive extract --tar "extracted.tar" D:\backups\repo::archive1

set BS_REPO="D:\backups\repo"
8BitSafe-cli.exe archive extract --tar "D:\backups\extracted.tar" ::archive1 "D:\some_path_in_the_archive\*"
8BitSafe-cli.exe archive extract --tar "pics_no_jpg.tar" ::archive1 "D:\Pictures\*" -e "*.jpg

Unix

8BitSafe-cli archive extract --tar "extracted.tar" /mnt/backups/repo::archive1

export BS_REPO="/mnt/backups/repo"
8BitSafe-cli archive extract --tar "/mnt/backups/extracted.tar" ::archive1 "/mnt/data/some_path_in_the_archive/*"
8BitSafe-cli archive extract --tar "pics_no_jpg.tar" ::archive1 "/mnt/data/Pictures/*" -e "*.jpg

Tar (Compressed)

Extracting to a compressed tar is also supported.

Enabling compression for tar is done via the file extension of the passed tar path.

Currently supported file extensions are:

extension	algo	mode	compression level
gz	gzip	Deflate	Default
zip	zip	Deflate	Default

Examples

info

Windows

8BitSafe-cli.exe archive extract --tar "extracted.tar.gz" D:\backups\repo::archive1
8BitSafe-cli.exe archive extract --tar "extracted.tar.zip" D:\backups\repo::archive1

Unix

8BitSafe-cli archive extract --tar "extracted.tar.gz" /mnt/backups/repo::archive1
8BitSafe-cli archive extract --tar "extracted.tar.zip" /mnt/backups/repo::archive1

Map

You can use the --map option to remap archive paths during extraction, this is useful for changing where files are extracted since typically archive paths are absolute.

The option takes an array of <sourcePrefix>,<target> pairs that are checked against each path during extract. The longest matching <sourcePrefix> is selected then replaced with <target>.

paths:

C:\Users\Tom\Tools\misc
C:\Users\Tom\Tools\misc\foo.exe
C:\Users\Tom\Tools\misc\bar.exe

Any you want to extract them to D:\tools\misc you could do so with the following mapping:
--map "C:\Users\Tom\Tools\" "D:\tools\"

The paths would be transformed as follows:

C:\Users\Tom\Tools\misc -> D:\tools\misc
C:\Users\Tom\Tools\misc\foo.exe -> D:\tools\misc\foo.exe
C:\Users\Tom\Tools\misc\bar.exe -> D:\tools\misc\bar.exe

Since the longest <sourcePrefix> is selected we can do things like this: --map "C:\Users\Tom\Tools\" "D:\tools\" "C:\Users\Tom\Tools\misc2\" "F:\"

The paths would be transformed as follows:

C:\Users\Tom\Tools\misc -> D:\tools\misc
C:\Users\Tom\Tools\misc\foo.exe -> D:\tools\misc\foo.exe
C:\Users\Tom\Tools\misc2\bar.exe -> F:\bar.exe

Even though C:\Users\Tom\Tools\ matches C:\Users\Tom\Tools\misc2\bar.exe we have a longer match that is selected placing it in F:\.

tip

You can use archive print with a depth of 1 to list root paths.

Cross platform

Another useful use of --map is when extracting archives on different platform as paths like
C:\Users\Tom\Tools\misc\foo.exe are not valid in unix.

So we can remap then like so --map "C:\Users\Tom\" "/home/tom/" or the other way --map "/home/tom/" "C:\Users\Tom\" when extracting on Windows.

Matching logic

The matching is case sensitive and must be a prefix. Wildcards or globs are not supported.

Various Examples

info

Some examples omit the repo path as we set BS_REPO.

Windows

8BitSafe-cli.exe archive extract D:\backups\repo::archive1

set BS_REPO="D:\backups\repo"
8BitSafe-cli.exe archive extract ::archive1 "C:\User\Tom\Docs\**"
8BitSafe-cli.exe archive extract ::archive1 "C:\User\Tom\Docs\**" "C:\User\Tom\Docs\notes.txt"
8BitSafe-cli.exe archive extract ::archive1 "C:\User\Tom\Docs\**"
8BitSafe-cli.exe archive extract -e "*.jpg" ::archive1 "C:\User\Tom\Images\**"
8BitSafe-cli.exe archive extract ::archive1 "C:\User\Tom\Images\**.{png,gif}"

Unix

8BitSafe-cli archive  extract /mnt/backups/repo::archive1

export BS_REPO="/mnt/backups/repo"
8BitSafe-cli archive extract ::archive1 "/home/tom/**"
8BitSafe-cli archive extract ::archive1 "/home/tom/**" "/home/bob/notes.txt"
8BitSafe-cli archive extract -e "*.jpg" ::archive1 "/home/tom/Images/**"
8BitSafe-cli archive extract ::archive1 "/home/tom/Images/**.{png,gif}"