[crossrootfs.git] / tar / tar.1

.\" @(#)tar.1 1.11.1 93/19/22 PJV;
.TH TAR 1 "15 May 2006"
.SH NAME
tar \- The GNU version of the tar archiving utility
.SH SYNOPSIS
.B tar
[
.B \-
]
.B A \-\-catenate \-\-concatenate \||\| c \-\-create \||\| d \-\-diff \-\-compare \||\| \-\-delete \||\| r \-\-append \||\| t \-\-list \||\| u \-\-update \||\| x \-\-extract \-\-get
.I [ options ]
.I pathname [ pathname ... ] 
.SH DESCRIPTION
.LP
This manual page documents the GNU version of
.B tar
, an archiving program designed to store and extract files from 
an archive file known as a 
.IR tarfile.
A 
.IR tarfile 
may be made on a tape drive, however, it is also common
to write a
.IR tarfile
to a normal file. 
The first argument to 
.B tar
must be one of the options:
.BR Acdrtux ,
followed by any optional functions.
The final arguments to 
.B tar
are the names of the files or directories which should be archived. The use
of a directory name always implies that the subdirectories below should be
included in the archive.
.SH EXAMPLES
.TP
.B tar \-xvvf foo.tar
extract foo.tar
.TP
.B tar \-xvvzf foo.tar.gz
extract gzipped foo.tar.gz
.TP
.B tar \-cvvf foo.tar foo/
tar contents of folder foo in foo.tar
.SH "FUNCTION LETTERS"
.TP
.B One of the following options must be used:
.TP
.B \-A, \-\-catenate, \-\-concatenate
append tar files to an archive
.TP
.B \-c, \-\-create	
create a new archive
.TP
.B \-d, \-\-diff, \-\-compare
find differences between archive and file system
.TP
.B \-\-delete		
delete from the archive (not for use on mag tapes!)
.TP
.B \-r, \-\-append		
append files to the end of an archive
.TP
.B \-t, \-\-list		
list the contents of an archive
.TP
.B \-u, \-\-update		
only append files that are newer than copy in archive
.TP
.B \-x, \-\-extract, \-\-get		
extract files from an archive
.SH "OTHER OPTIONS"
.TP
.B \-\-allow\-name\-mangling
re-enable handling of GNUTYPE_NAMES which is now disabled by default
.TP
.B \-\-anchored	
force exclusion patterns to match initial subsequences
.TP
.B \-\-atime\-preserve	
don't change access times on dumped files
.TP
.B \-b, \-\-blocking\-factor N
use record size of Nx512 bytes (default N=20)
.TP
.B \-B, \-\-read\-full\-records
reblock as we read (for reading 4.2BSD pipes)
.TP
.B \-\-backup[\=TYPE]
back up files instead of overwriting (TYPE=numbered, existing, simple)
.TP 
.B \-C, \-\-directory DIR	
change to directory DIR
.TP 
.B \-\-checkpoint		
print periodic checkpoints
.TP
.B \-\-exclude=PATTERN
exclude files matching PATTERN
.TP
.B \-f, \-\-file [HOSTNAME:]F	
use archive file or device F (default "\-", meaning stdin/stdout)
.TP 
.B \-F, \-\-info\-script F, \-\-new\-volume\-script F 
run script at end of each tape (implies \-M)
.TP
.B \-\-force\-local		
archive file is local even if it has a colon
.TP
.B \-G, \-\-incremental	
create/list/extract old GNU-format incremental backup
.TP
.B \-g, \-\-listed\-incremental F 
create/list/extract new GNU-format incremental backup
.TP
.B \-\-group G
set group to G while adding files
.TP 
.B \-h, \-\-dereference	
don't dump symlinks; dump the files they point to
.TP
.B \-\-help
print help message
.TP
.B \-i, \-\-ignore\-zeros	
ignore blocks of zeros in archive (normally mean EOF)
.TP
.B \-\-ignore\-case
ignore case when excluding files
.TP
.B \-\-ignore\-failed\-read	
don't exit with non-zero status on unreadable files
.TP
.B \-j, \-\-bzip2
filter archive through bzip2, use to decompress .bz2 files.
WARNING: some previous versions of tar used option \-I to 
filter through bzip2.  When writing scripts, use \-\-bzip2 
instead of \-j so that both older and newer tar versions
will work.
.TP
.B \-k, \-\-keep\-old\-files	
keep existing files; don't overwrite them from archive
.TP
.B \-K, \-\-starting\-file F	
begin at file F in the archive
.TP
.B \-l, \-\-check\-links
print a message if not all links are dumped
.TP
.B \-L, \-\-tape\-length N	
change tapes after writing N*1024 bytes
.TP
.B \-m, \-\-touch
don't extract file modified time
.TP
.B \-M, \-\-multi\-volume	
create/list/extract multi-volume archive
.TP
.B \-\-mode M
set permissions to M while adding files
.TP
.B \-N, \-\-after\-date DATE, \-\-newer DATE
only store files newer than DATE
.TP
.B \-\-newer\-mtime DATE
only store files whose contents have changed after DATE
.TP
.B \-\-no\-anchored
allow exclusion patterns to match any substring (the default)
.TP
.B \-\-no\-ignore\-case
match patterns case sensitively (the default)
.TP
.B \-\-no\-recursion
do not recurse into subdirectories
.TP
.B \-o, \-\-no\-same\-owner
extract files with owner set to current user (the default for non-root
users)
.TP
.B \-\-no\-same\-permissions
apply umask to extracted files (the default for non-root users)
.TP
.B \-\-no\-wildcards
do not use wildcards when excluding files
.TP
.B \-\-no\-wildcards\-match\-slash
don't let wildcards match "/" when excluding files
.TP
.B \-\-null
for \-T, use "NUL" instead of newline as filename terminator
.TP
.B \-\-numeric\-owner
always use numbers for user/group names
.TP
.B \-\-old\-archive, \-\-portability	
write a V7 format archive, rather than ANSI format.  These options are
deprecated, please use 
.B \-\-format\=v7
instead.
.TP
.B \-\-one\-file\-system	
stay in local file system when creating an archive
.TP
.B \-\-owner O
set owner to O while adding files
.TP 
.B \-O, \-\-to\-stdout		
extract files to standard output
.TP
.B \-p, \-\-same\-permissions, \-\-preserve\-permissions 
ignore umask when extracting files (the default for root)
.TP
.B \-P, \-\-absolute\-names
don't strip leading `/'s from file names
.TP
.B \-\-posix
create POSIX compliant archive.  This option is deprecated,
please use 
.B \-\-format\=posix
instead.
.TP
.B \-\-preserve		
like \-p \-s
.TP
.B \-R, \-\-block\-number	
show block number within archive with each message
.TP
.B \-\-record\-size SIZE
use SIZE bytes per record
.TP
.B \-\-recursion
recurse into directories (the default)
.TP
.B \-\-recursive\-unlink
remove existing directories before extracting directories of the same
name
.TP 
.B \-\-remove\-files		
remove files after adding them to the archive
.TP
.B \-\-rsh\-command=CMD
Use remote COMMAND instead of `rsh'.  This option exists so that
people who use something other than the standard `rsh' (e.g., a
Kerberized `rsh') can access a remote device.
.TP
.B \-S, \-\-sparse		
handle sparse files efficiently
.TP
.B \-s, \-\-same\-order, \-\-preserve\-order	
list of names to extract is sorted to match archive
.TP
.B \-\-same\-owner		
extract files with owner as specified in archive (the default for
root)
.TP
.B \-\-show\-omitted\-dirs
mention directories that are being skipped over
.TP
.B \-\-suffix SUFFIX
append SUFFIX to make backup files (default ~)
.TP 
.B \-T, \-\-files\-from F	
get names to extract or archive from file F
.TP
.B \-\-totals
display total bytes written after creating an archive
.TP
.B \-U, \-\-unlink\-first
unlink & recreate files instead of overwriting
.TP
.B \-\-use\-compress\-program PROG
filter the archive through PROG (which must accept \-d)
.TP
.B \-v, \-\-verbose		
verbosely list files processed
.TP
.B \-V, \-\-label NAME	
create archive with volume name NAME
.TP 
.B \-\-version		
print tar program version number
.TP
.B \-\-volno\-file F
keep track of current volume (of a multi-volume archive) in F
.TP
.B \-w, \-\-interactive, \-\-confirmation	
ask for confirmation for every action
.TP
.B \-W, \-\-verify		
attempt to verify the archive after writing it
.TP
.B \-\-wildcards
use wildcards when excluding files (the default)
.TP
.B \-\-wildcards\-match\-slash
allow wildcards to match "/" (the default)
.TP
.B \-X, \-\-exclude\-from=FILE	
exclude files matching patterns listed in FILE
.TP
.B \-Z, \-\-compress, \-\-uncompress      	
filter the archive through compress
.TP 
.B \-z, \-\-gzip, \-\-gunzip, \-\-ungzip		
filter the archive through gzip
.TP
.B \-[0\-7][lmh]		
specify drive and density
.SH BUGS
.LP
The GNU folks, in general, abhor man pages, and create info documents instead.
Unfortunately, the info document describing tar is licensed under the GFDL with
invariant cover texts, which violates the Debian Free Software Guidelines.  As
a result, the info documentation for tar is not included in the Debian package.

If you want to read the complete documentation for GNU tar, please refer to
the online version at <http://www.gnu.org/software/tar/manual/index.html>.

This man page was created for the Debian distribution.  It does not describe
all of the functionality of tar, and it is often out of date.  Patches to 
improve the coverage and/or accuracy of this man page are appreciated, and
should be filed as wishlist severity bugs against the Debian tar package, 
not submitted to the GNU tar maintainers.
Commit	Line	Data
6dca1d21 JB	1	.\" @(#)tar.1 1.11.1 93/19/22 PJV;
	2	.TH TAR 1 "15 May 2006"
	3	.SH NAME
	4	tar \- The GNU version of the tar archiving utility
	5	.SH SYNOPSIS
	6	.B tar
	7	[
	8	.B \-
	9	]
	10	.B A \-\-catenate \-\-concatenate \\|\|\\| c \-\-create \\|\|\\| d \-\-diff \-\-compare \\|\|\\| \-\-delete \\|\|\\| r \-\-append \\|\|\\| t \-\-list \\|\|\\| u \-\-update \\|\|\\| x \-\-extract \-\-get
	11	.I [ options ]
	12	.I pathname [ pathname ... ]
	13	.SH DESCRIPTION
	14	.LP
	15	This manual page documents the GNU version of
	16	.B tar
	17	, an archiving program designed to store and extract files from
	18	an archive file known as a
	19	.IR tarfile.
	20	A
	21	.IR tarfile
	22	may be made on a tape drive, however, it is also common
	23	to write a
	24	.IR tarfile
	25	to a normal file.
	26	The first argument to
	27	.B tar
	28	must be one of the options:
	29	.BR Acdrtux ,
	30	followed by any optional functions.
	31	The final arguments to
	32	.B tar
	33	are the names of the files or directories which should be archived. The use
	34	of a directory name always implies that the subdirectories below should be
	35	included in the archive.
	36	.SH EXAMPLES
	37	.TP
	38	.B tar \-xvvf foo.tar
	39	extract foo.tar
	40	.TP
	41	.B tar \-xvvzf foo.tar.gz
	42	extract gzipped foo.tar.gz
	43	.TP
	44	.B tar \-cvvf foo.tar foo/
	45	tar contents of folder foo in foo.tar
	46	.SH "FUNCTION LETTERS"
	47	.TP
	48	.B One of the following options must be used:
	49	.TP
	50	.B \-A, \-\-catenate, \-\-concatenate
	51	append tar files to an archive
	52	.TP
	53	.B \-c, \-\-create
	54	create a new archive
	55	.TP
	56	.B \-d, \-\-diff, \-\-compare
	57	find differences between archive and file system
	58	.TP
	59	.B \-\-delete
	60	delete from the archive (not for use on mag tapes!)
	61	.TP
	62	.B \-r, \-\-append
	63	append files to the end of an archive
	64	.TP
65	.B \-t, \-\-list
66	list the contents of an archive
67	.TP
68	.B \-u, \-\-update
69	only append files that are newer than copy in archive
70	.TP
71	.B \-x, \-\-extract, \-\-get
72	extract files from an archive
73	.SH "OTHER OPTIONS"
74	.TP
75	.B \-\-allow\-name\-mangling
76	re-enable handling of GNUTYPE_NAMES which is now disabled by default
77	.TP
78	.B \-\-anchored
79	force exclusion patterns to match initial subsequences
80	.TP
81	.B \-\-atime\-preserve
82	don't change access times on dumped files
83	.TP
84	.B \-b, \-\-blocking\-factor N
85	use record size of Nx512 bytes (default N=20)
86	.TP
87	.B \-B, \-\-read\-full\-records
88	reblock as we read (for reading 4.2BSD pipes)
89	.TP
90	.B \-\-backup[\=TYPE]
91	back up files instead of overwriting (TYPE=numbered, existing, simple)
92	.TP
93	.B \-C, \-\-directory DIR
94	change to directory DIR
95	.TP
96	.B \-\-checkpoint
97	print periodic checkpoints
98	.TP
99	.B \-\-exclude=PATTERN
100	exclude files matching PATTERN
101	.TP
102	.B \-f, \-\-file [HOSTNAME:]F
103	use archive file or device F (default "\-", meaning stdin/stdout)
104	.TP
105	.B \-F, \-\-info\-script F, \-\-new\-volume\-script F
106	run script at end of each tape (implies \-M)
107	.TP
108	.B \-\-force\-local
109	archive file is local even if it has a colon
110	.TP
111	.B \-G, \-\-incremental
112	create/list/extract old GNU-format incremental backup
113	.TP
114	.B \-g, \-\-listed\-incremental F
115	create/list/extract new GNU-format incremental backup
116	.TP
117	.B \-\-group G
118	set group to G while adding files
119	.TP
120	.B \-h, \-\-dereference
121	don't dump symlinks; dump the files they point to
122	.TP
123	.B \-\-help
124	print help message
125	.TP
126	.B \-i, \-\-ignore\-zeros
127	ignore blocks of zeros in archive (normally mean EOF)
128	.TP
129	.B \-\-ignore\-case
130	ignore case when excluding files
131	.TP
132	.B \-\-ignore\-failed\-read
133	don't exit with non-zero status on unreadable files
134	.TP
135	.B \-j, \-\-bzip2
136	filter archive through bzip2, use to decompress .bz2 files.
137	WARNING: some previous versions of tar used option \-I to
138	filter through bzip2. When writing scripts, use \-\-bzip2
139	instead of \-j so that both older and newer tar versions
140	will work.
141	.TP
142	.B \-k, \-\-keep\-old\-files
143	keep existing files; don't overwrite them from archive
144	.TP
145	.B \-K, \-\-starting\-file F
146	begin at file F in the archive
147	.TP
148	.B \-l, \-\-check\-links
149	print a message if not all links are dumped
150	.TP
151	.B \-L, \-\-tape\-length N
152	change tapes after writing N*1024 bytes
153	.TP
154	.B \-m, \-\-touch
155	don't extract file modified time
156	.TP
157	.B \-M, \-\-multi\-volume
158	create/list/extract multi-volume archive
159	.TP
160	.B \-\-mode M
161	set permissions to M while adding files
162	.TP
163	.B \-N, \-\-after\-date DATE, \-\-newer DATE
164	only store files newer than DATE
165	.TP
166	.B \-\-newer\-mtime DATE
167	only store files whose contents have changed after DATE
168	.TP
169	.B \-\-no\-anchored
170	allow exclusion patterns to match any substring (the default)
171	.TP
172	.B \-\-no\-ignore\-case
173	match patterns case sensitively (the default)
174	.TP
175	.B \-\-no\-recursion
176	do not recurse into subdirectories
177	.TP
178	.B \-o, \-\-no\-same\-owner
179	extract files with owner set to current user (the default for non-root
180	users)
181	.TP
182	.B \-\-no\-same\-permissions
183	apply umask to extracted files (the default for non-root users)
184	.TP
185	.B \-\-no\-wildcards
186	do not use wildcards when excluding files
187	.TP
188	.B \-\-no\-wildcards\-match\-slash
189	don't let wildcards match "/" when excluding files
190	.TP
191	.B \-\-null
192	for \-T, use "NUL" instead of newline as filename terminator
193	.TP
194	.B \-\-numeric\-owner
195	always use numbers for user/group names
196	.TP
197	.B \-\-old\-archive, \-\-portability
198	write a V7 format archive, rather than ANSI format. These options are
199	deprecated, please use
200	.B \-\-format\=v7
201	instead.
202	.TP
203	.B \-\-one\-file\-system
204	stay in local file system when creating an archive
205	.TP
206	.B \-\-owner O
207	set owner to O while adding files
208	.TP
209	.B \-O, \-\-to\-stdout
210	extract files to standard output
211	.TP
212	.B \-p, \-\-same\-permissions, \-\-preserve\-permissions
213	ignore umask when extracting files (the default for root)
214	.TP
215	.B \-P, \-\-absolute\-names
216	don't strip leading `/'s from file names
217	.TP
218	.B \-\-posix
219	create POSIX compliant archive. This option is deprecated,
220	please use
221	.B \-\-format\=posix
222	instead.
223	.TP
224	.B \-\-preserve
225	like \-p \-s
226	.TP
227	.B \-R, \-\-block\-number
228	show block number within archive with each message
229	.TP
230	.B \-\-record\-size SIZE
231	use SIZE bytes per record
232	.TP
233	.B \-\-recursion
234	recurse into directories (the default)
235	.TP
236	.B \-\-recursive\-unlink
237	remove existing directories before extracting directories of the same
238	name
239	.TP
240	.B \-\-remove\-files
241	remove files after adding them to the archive
242	.TP
243	.B \-\-rsh\-command=CMD
244	Use remote COMMAND instead of `rsh'. This option exists so that
245	people who use something other than the standard `rsh' (e.g., a
246	Kerberized `rsh') can access a remote device.
247	.TP
248	.B \-S, \-\-sparse
249	handle sparse files efficiently
250	.TP
251	.B \-s, \-\-same\-order, \-\-preserve\-order
252	list of names to extract is sorted to match archive
253	.TP
254	.B \-\-same\-owner
255	extract files with owner as specified in archive (the default for
256	root)
257	.TP
258	.B \-\-show\-omitted\-dirs
259	mention directories that are being skipped over
260	.TP
261	.B \-\-suffix SUFFIX
262	append SUFFIX to make backup files (default ~)
263	.TP
264	.B \-T, \-\-files\-from F
265	get names to extract or archive from file F
266	.TP
267	.B \-\-totals
268	display total bytes written after creating an archive
269	.TP
270	.B \-U, \-\-unlink\-first
271	unlink & recreate files instead of overwriting
272	.TP
273	.B \-\-use\-compress\-program PROG
274	filter the archive through PROG (which must accept \-d)
275	.TP
276	.B \-v, \-\-verbose
277	verbosely list files processed
278	.TP
279	.B \-V, \-\-label NAME
280	create archive with volume name NAME
281	.TP
282	.B \-\-version
283	print tar program version number
284	.TP
285	.B \-\-volno\-file F
286	keep track of current volume (of a multi-volume archive) in F
287	.TP
288	.B \-w, \-\-interactive, \-\-confirmation
289	ask for confirmation for every action
290	.TP
291	.B \-W, \-\-verify
292	attempt to verify the archive after writing it
293	.TP
294	.B \-\-wildcards
295	use wildcards when excluding files (the default)
296	.TP
297	.B \-\-wildcards\-match\-slash
298	allow wildcards to match "/" (the default)
299	.TP
300	.B \-X, \-\-exclude\-from=FILE
301	exclude files matching patterns listed in FILE
302	.TP
303	.B \-Z, \-\-compress, \-\-uncompress
304	filter the archive through compress
305	.TP
306	.B \-z, \-\-gzip, \-\-gunzip, \-\-ungzip
307	filter the archive through gzip
308	.TP
309	.B \-[0\-7][lmh]
310	specify drive and density
311	.SH BUGS
312	.LP
313	The GNU folks, in general, abhor man pages, and create info documents instead.
314	Unfortunately, the info document describing tar is licensed under the GFDL with
315	invariant cover texts, which violates the Debian Free Software Guidelines. As
316	a result, the info documentation for tar is not included in the Debian package.
317
318	If you want to read the complete documentation for GNU tar, please refer to
319	the online version at <http://www.gnu.org/software/tar/manual/index.html>.
320
321	This man page was created for the Debian distribution. It does not describe
322	all of the functionality of tar, and it is often out of date. Patches to
323	improve the coverage and/or accuracy of this man page are appreciated, and
324	should be filed as wishlist severity bugs against the Debian tar package,
325	not submitted to the GNU tar maintainers.