Manual page is hold just for quick refreshing memory.  It is generated
using help2man program (and it is distributed only by Red Hat distros, as
upstream does not distribute any man page).  You are able to find whole
documentation for GNU tar using 'info' (or 'pinfo').  Official documentation is
for sure online in multiple formats (same data as in info pages).

All Options -> Option Summary -> (find --exclude) -> *Note exclude:: -> OK

There are other ways how to find this.

Pavel

> All Options -> Option Summary -> (find --exclude) -> *Note exclude:: -> OK

This ^^ is one of many routes usable to find you are looking for by 'info tar'.

Pavel

I can't see any additional information using info. No explanation how does it handle * (e.g. does it mean anything or anything except slash), does ** have any special meaning, can absolute paths be used and what semantics. There is only a bare limited example. Even in the simplest case that only * is supported and that means anything including slash, then that needs to be explained.

Please let me know if I am missing something. Perhaps I just can't see where is that explained.

Cite:

| 6.4 Excluding Some Files
| ========================
| To avoid operating on files whose names match a particular pattern, use
| the `--exclude' or `--exclude-from' options.
|
| `--exclude=PATTERN'
|      Causes `tar' to ignore files that match the PATTERN.
|
|    The `--exclude=PATTERN' option prevents any file or member whose
| name matches the shell wildcard (PATTERN) from being operated on.  For
| example, to create an archive with all the contents of the directory
| `src' except for files whose names end in `.o', use the command `tar
| -cf src.tar --exclude='*.o' src'.

OK, this is pretty, the keyword could be 'shell wildcard'.  But tar's wildcards
are pretty good explained in section 6.5.  Just try to look for 'wildcards'.

| 6.5 Wildcards Patterns and Matching
| ===================================
|
| [...snip ...]
|
|    A PATTERN should be written according to shell syntax, using wildcard
| characters to effect globbing.  Most characters in the pattern stand
| for themselves in the matched string, and case is significant: `a' will
| match only `a', and not `A'.  The character `?' in the pattern matches
| any single character in the matched string.  The character `*' in the
| pattern matches zero, one, or more single characters in the matched
| string.  The character `\' says to take the following character of the
| pattern _literally_; it is useful when one needs to match the `?', `*',
| `[' or `\' characters, themselves.
| [ .. pretty long snip .. ]

The quality of documentation is never as good as it could be.  But it looks
quite sufficient.  Tar's upstream has quite good manual available in format you
prefer.

Pavel

Aleksandar, thanks for the report anyway,

> Please let me know if I am missing something. Perhaps I just can't see where
> is that explained.

I'm of course free to discuss what could be done better.  If you found this
insufficient - let me know - I'd be glad to help you.

TIA,
Pavel

The section 6.5 you pointed me at does really explain what kind of patterns are understood. I think that these things can help:
1. (info page) have a reference from the --exclude option description to the section 6.5. Without this I'm not sure how anybody would find it.
2. (man page) in the --exclude explanation, refer user to the info page for additional information
3. (info page) add examples in the section 6.5

But really #1 and #2 are straightforward and should not be time consuming. In my opinion these two will cover most user misconception.

Thank you.

> The section 6.5 you pointed me at does really explain what kind of patterns
> are understood. I think that these things can help:
> 1. (info page) have a reference from the --exclude option description to the
> section 6.5. Without this I'm not sure how anybody would find it.

Do you think that following patch is sufficient?  I'm just not sure if this
could became part of upstream documentation, as both @xrefed sections
immediately follow the --exclude description.

 | diff --git a/doc/tar.texi b/doc/tar.texi
 | index 4a49282..30fc400 100644
 | --- a/doc/tar.texi
 | +++ b/doc/tar.texi
 | @@ -7195,7 +7195,9 @@ member whose name matches the shell wildcard (@var{pattern}) from
 |  being operated on.
 |  For example, to create an archive with all the contents of the directory
 |  @file{src} except for files whose names end in @file{.o}, use the
 | -command @samp{tar -cf src.tar --exclude='*.o' src}.
 | +command @samp{tar -cf src.tar --exclude='*.o' src}.  Reading of following
 | +sections is encouraged.  @xref{problems with exclude}, for exclude pitfails.
 | +@xref{wildcards}, for more info about wildcards.
 |
 |  You may give multiple @option{--exclude} options.

Also, both sites are referenced already.  Wildcards are mentioned in info
menu like the following section.  And problems with exclude are mentioned
at the bottom of the page in submenu.

If you use the pdf manual, this seems to be even more redundant as use
has continuous document.  Info pages are also continuous, but it is not so
obvious.

But we could give it a try, what do you think?

> 2. (man page) in the --exclude explanation, refer user to the info page for
> additional information

I don't think this is good idea.  Look at the 'SEE ALSO' section.  There
is quite obvious that user should use info pages.  We need to hold man
page as simple as possible.  Not only --exclude option is enough
difficult to be mentioned like this.

> 3. (info page) add examples in the section 6.5

I would go for this also, but give me please examples you would like to
see there.  And the place where you would like to put this.

Pavel

Sorry for delay, had other duties.

#1 looks good to me

#2 I would suggest to have the warning at the beginning of the man page so the first lines tell user that there is more complete manual elsewhere. too much to ask?

#3 Here are a couple

imagine structure like
/path/file1
/path/file2
/path/level1/file1
/path/level1/file2
/path/level1/level2/file1
/path/level1/level2/file2
/path/level1/level2/level3/file1
/path/level1/level2/level3/file2

*how to exclude only file1 in the level1 dir
*how to exclude all "file2" named files
*how to exclude "file2" named files only under the level2 dir
*how to exclude everything under level2 dir

I think this covers it all. Thank you for listening!

To be clear I mean a tar command archiving everything under /path/, e.g.
tar cvfz /tmp/my.tgz -C /path/

> #2 I would suggest to have the warning at the beginning of the man page so
> the first lines tell user that there is more complete manual elsewhere. too
> much to ask?

Nope, its ok IMO :) but it is something else than:

>> 2. (man page) in the --exclude explanation, refer user to the info page
>>    for additional information

I am quite OK with the SEE ALSO place as it is really common place where
to mention Texinfo manual (at least in GNU projects).

Anyway, the manual page in rawhide was quite not up2date.  I have pushed
some changes into manual tar.1 manpage including your suggestion (as we
are not changing upstream man page source).  This may be considered as
better place for GNU tar.  Could you check if it is ok for you?

> #3 Here are a couple
> [...]
> *how to exclude everything under level2 dir
> 
> I think this covers it all. Thank you for listening!

I'll look at these ^^^.  Thanks.

Pavel

> I have pushed some changes into manual tar.1 manpage including your suggestion (as we are not changing upstream man page source).  This may be considered as better place for GNU tar.  Could you check if it is ok for you?

Where can I do so? I'm not familiar with places I can find updates :/

> I have pushed some changes into manual tar.1 manpage including your suggestion
> (as we are not changing upstream man page source).  This may be considered as
> better place for GNU tar.  Could you check if it is ok for you?
>
> Where can I do so? I'm not familiar with places I can find updates :/

Here is a link to rawhide build:

    https://koji.fedoraproject.org/koji/buildinfo?buildID=381773

Git source is here:

    http://pkgs.fedoraproject.org/cgit/tar.git/tree/

Pavel

Nice, I couldn't install the package but extracted the docs. Besides the examples I think that resolves my concerns.

Thank you again!

Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

http://rhn.redhat.com/errata/RHBA-2014-1382.html