This is the development version of Kanrisuru. Since this is still a pre-1.0 release, we don't recommend using this in system-critical production environments.

Kanrisuru

tar

Save, manage and extract groups of files in an archive with ruby.
linux manual

Basic Usage

require 'kanrisuru'
host = Kanrisuru::Remote::Host.new(host: '127.0.1.1', username: 'ubuntu', keys: ['~/.ssh/id_rsa'])

## Create an archive with the "directory" path. Relative to /home/ubuntu
result = host.tar('create', 'archive.tar', paths: 'directory')
result.success?
true

## Get contents of the directory
host.tar('list', '~/archive.tar').map(&:path)
[
  "directory/",
  "directory/file1.txt",
  "directory/file2.txt",
  "directory/file3.txt"
]

## Add new file to the tar archive 
host.touch('~/directory/file4.txt').success?
true

host.tar('append', '~/archive.tar', paths: 'directory/file4.txt').success?
true

## View new file added to the archive
result = host.tar('list', '~/archive.tar').map(&:path)
[
  "directory/",
  "directory/file1.txt",
  "directory/file2.txt",
  "directory/file3.txt",
  "directory/file4.txt"
]

## Extract files, overwrite already existing files 
host.tar('extract', '~/archive.tar', overwrite: true).success?
true

host.ls(path: '~/directory').map(&:path)
[
  "file1.txt",
  "file2.txt",
  "file3.txt",
  "file4.txt"
]

Actions

name description
create Create an archive from a selection of files, create and c perform the same action
list List files in an archive, list and t perform the same action
extract Extract files from an archive, extract, x, and get perform the same action
append Append files to an existing archive, append and r perform the same action.
concat Combine multiple archives into a single archive, concat, A, and catenate perform the same action
update Update a file in an existing archive, update and u perform the same action
diff Find the differences between an archive and a filesystem, diff, d, and compare perform the same action
delete Delete a file(s) from an existing archive

Common Parameters

Field Type Description
action string
Required action to perform for the tar archive. One of create, list, extract, append, concat, update, diff, and delete. See each section below for more details
file string
Required name of the archive file path to operate on
directory string
Directory to change to when performing action for archiving
compress string
Use an optional compression algorithm when performing actions on the archive. Choose from bzip2, xz, gzip, and lzma.

Create

Create an archive from a selection of files, create and c perform the same action

Parameters

Field Type Description
paths string
array
A set of file(s) and directories to include in the archive
exclude string
array
A set of files and directories to exclude in the archive. Can use globbing patterns to match file types to exclude

Result

No explicit data struct returned, only option is success?, failure?, and status to see if the program exited properly.

Example

result = host.tar('c', 'archive.tar', 
  exclude: '*.conf', 
  paths: ['directory', 'file3.txt', 'file4.txt'], 
  compress: 'gzip'
)

result.success?
true

Exit Status

Code Description
0 Success
1 Some files differ. Some files were changed while being archived and so the resulting archive does not contain the exact copy of the file set.
2 Fatal error. This means that some fatal, unrecoverable error occurred.

List

List files in an archive, list and t perform the same action

Parameters

Field Type Description
label boolean
create archive with volume name TEXT; at list/extract time, use TEXT as a globbing pattern for volume name
occurrence string
Process only the Nth occurrence of each file in the archive. The default N is 1

Result

Returns an array of FilePath structs.

FilePath Fields

Field Type Description
path string Location of the file in the archive.

Example

host.tar('t', 'archive.tar', occurrence: 'directory/*.txt')
[
  #<Struct:Kanrisuru::Core::Archive::FilePath:0x00001720
    path = "directory/file1.txt"
  >,
  #<Struct:Kanrisuru::Core::Archive::FilePath:0x00001770
    path = "directory/file2.txt"
  >,
  #<Struct:Kanrisuru::Core::Archive::FilePath:0x000017c0
    path = "directory/file3.txt"
  >,
  #<Struct:Kanrisuru::Core::Archive::FilePath:0x00001810
    path = "directory/file4.txt"
  >
]

Exit Status

Code Description
0 Success
2 Fatal error. This means that some fatal, unrecoverable error occurred.

Extract

Extract files from an archive, extract, x, and get perform the same action.

Parameters

Field Type Description
occurrence string
Process only the Nth occurrence of each file in the archive. The default N is 1
paths string
array
Extract individual files / directories from the archive
label boolean
create archive with volume name TEXT; at list/extract time, use TEXT as a globbing pattern for volume name
no_same_owner boolean
Extract files as yourself (default for ordinary users)
no_same_permissions boolean
Apply the user's umask when extracting permissions from the archive (default for ordinary users)
no_selinux boolean
Don't extract the SELinux context from the archive
no_xattrs boolean
Don't extract the user/root xattrs from the archive
preserve_permissions boolean
Extract information about file permissions (default for superuser)
same_owners boolean
Try extracting files with the same ownership as exists in the archive (default for superuser)
one_file_system boolean
Stay in local file system when creating archive
keep_old_files boolean
Don't replace existing files when extracting, treat them as errors
skip_old_files boolean
Don't replace existing files when extracting, silently skip over them
overwrite boolean
Overwrite existing files when extracting
overwrite_dir boolean
Overwrite metadata of existing directories when extracting (default)
unlink_first boolean
Remove each file prior to extracting over it
recursive_unlink boolean
Empty hierarchies prior to extracting directory

Result

No explicit data struct returned, only option is success?, failure?, and status to see if the program exited properly.

Example

result = host.tar('x', '~/archive.tar', overwrite: true)
result.success?
true

Exit Status

Code Description
0 Success
2 Fatal error. This means that some fatal, unrecoverable error occurred.

Append

Append files to an existing archive, append and r perform the same action.

Parameters

Field Type Description
paths string
array
Locations of other files / directories to add the archive

Result

No explicit data struct returned, only option is success?, failure?, and status to see if the program exited properly.

Example

result = host.tar('r', '~/archive.tar', paths: ['file4.txt', 'file5.txt'])
result.success?
true

Exit Status

Code Description
0 Success
1 Some files differ. Some files were changed while being archived and so the resulting archive does not contain the exact copy of the file set.
2 Fatal error. This means that some fatal, unrecoverable error occurred.

Concat

Combine multiple archives into a single archive, concat, A, and catenate perform the same action.

Compressed archives cannot be concatenated

Parameters

Field Type Description
paths string
array
Locations of other archives to add to the main archive

Result

No explicit data struct returned, only option is success?, failure?, and status to see if the program exited properly.

Example

result = host.tar('A', 'archive.tar', paths: 'archive2.tar')
result.success?
true

host.tar('t', 'archive.tar').map(&:path)
[
  'directory/',
  'directory/file1.txt',
  'directory/file2.txt',
  'directory/file3.txt',
  'tmp/test1.conf',
  'tmp/test2.conf',
  'tmp/test3.conf'
]

Exit Status

Code Description
0 Success
2 Fatal error. This means that some fatal, unrecoverable error occurred.

Update

Update a file in an existing archive, update and u perform the same action.

Parameters

Field Type Description
paths string
array
Which files / directories in the archive to update

Result

No explicit data struct returned, only option is success?, failure?, and status to see if the program exited properly.

Example

host.echo('hello world', new_file: '~/directory/file1.txt', mode: 'append').success?
true

host.tar('u', 'archive.tar', paths: 'directory/file1.txt').success?
true

Exit Status

Code Description
0 Success
1 Some files differ. Some files were changed while being archived and so the resulting archive does not contain the exact copy of the file set.
2 Fatal error. This means that some fatal, unrecoverable error occurred.

Diff

Find the differences between an archive and a filesystem, diff, d, and compare perform the same action.

Parameters

Field Type Description
occurrence string
Process only the Nth occurrence of each file in the archive. The default N is 1

Result

No explicit data struct returned, only option is success?, failure?, and status to see if the program exited properly.

Example

host.echo('hello world', new_file: '~/directory/file1.txt', mode: 'append').success?
true

host.tar('d', 'archive.tar')
host.success?
false

host.status
1

Exit Status

Code Description
0 Success
1 Some files differ. Some files in the archive differ from their disk counterparts.
2 Fatal error. This means that some fatal, unrecoverable error occurred.

Delete

Delete a file(s) from an existing archive.

Files cannot be deleted from a compressed archive

Parameters

Field Type Description
occurrence string
Process only the Nth occurrence of each file in the archive. The default N is 1
paths string
array
Which files / directories in the archive to delete

Result

No explicit data struct returned, only option is success?, failure?, and status to see if the program exited properly.

Example

host.tar('delete', 'archive.tar', paths: ['directory/file1.txt', 'directory/file3.txt']).success?
true

host.tar('t', 'archive.tar').map(&:path)
[
  'directory/',
  'directory/file2.txt'
  'directory/file4.txt'
]

Exit Status

Code Description
0 Success
2 Fatal error. This means that some fatal, unrecoverable error occurred.

Tested On

  • Ubuntu, Debian, Centos, Fedora, Redhat, OpenSuse, SLES