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