summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJames Youngman <jay@gnu.org>2019-09-01 14:55:57 +0100
committerJames Youngman <jay@gnu.org>2019-09-01 14:55:57 +0100
commit855dbdadbf75ca1f08f3e1c7c6811670e952d906 (patch)
tree754dd6295cf395cbe7a85a4df6ff3048220e22d4
parent45d1608eb45266fcf68cac7dcacbfd2ddfe0b875 (diff)
downloadfindutils-855dbdadbf75ca1f08f3e1c7c6811670e952d906.tar.gz
find: Clarify description of %f and %h.
Fix https://savannah.gnu.org/bugs/index.php?35253 * doc/find.texi (Name Directives): Clarify description of %f and %h. * find/find.1 (-printf): Likewise. * NEWS: mention this change.
-rw-r--r--NEWS2
-rw-r--r--doc/find.texi29
-rw-r--r--find/find.140
3 files changed, 61 insertions, 10 deletions
diff --git a/NEWS b/NEWS
index 74cf772..cb84faf 100644
--- a/NEWS
+++ b/NEWS
@@ -8,6 +8,8 @@ GNU findutils NEWS - User visible changes. -*- outline -*- (allout)
#48135: Fix testsuite error on Hurd and BSD related to ln
+#35253: Clarify descriptions of -printf %f, %h.
+
* Major changes in release 4.7.0, 2019-08-29
** Changes to locate / updatedb
diff --git a/doc/find.texi b/doc/find.texi
index d48d178..fbfa57e 100644
--- a/doc/find.texi
+++ b/doc/find.texi
@@ -1837,15 +1837,15 @@ it was encountered by @code{find} - that is, as a relative path from
one of the starting points).
@item %f
File's name with any leading directories removed (only the last
-element).
+element). That is, the basename of the file.
@c supports %-X.Yf
@item %h
Leading directories of file's name (all but the last element and the
-slash before it). If the file's name contains no slashes (for example
-because it was named on the command line and is in the current working
-directory), then ``%h'' expands to ``.''. This prevents ``%h/%f''
-expanding to ``/foo'', which would be surprising and probably not
-desirable.
+slash before it). That is, the dirname of the file. If the file's
+name contains no slashes (for example because it was named on the
+command line and is in the current working directory), then ``%h''
+expands to ``.''. This prevents ``%h/%f'' expanding to ``/foo'',
+which would be surprising and probably not desirable.
@c supports %-X.Yh
@item %P
File's name with the name of the command line argument under which
@@ -1856,6 +1856,23 @@ Command line argument under which file was found.
@c supports %-X.YH
@end table
+For some corner-cases, the interpretation of the @samp{%f} and
+@samp{%h} format directives is not obvious. Here is an eample
+including some output:
+
+@example
+$ find \
+ . .. / /tmp /tmp/TRACE compile compile/64/tests/find \
+ -maxdepth 0 -printf '%p: [%h][%f]\n'
+.: [.][.]
+..: [.][..]
+/: [][/]
+/tmp: [][tmp]
+/tmp/TRACE: [/tmp][TRACE]
+compile: [.][compile]
+compile/64/tests/find: [compile/64/tests][find]
+@end example
+
@node Ownership Directives
@subsubsection Ownership Directives
diff --git a/find/find.1 b/find/find.1
index 38e8518..91c0c85 100644
--- a/find/find.1
+++ b/find/find.1
@@ -1489,7 +1489,15 @@ File's depth in the directory tree; 0 means the file is a starting-point.
The device number on which the file exists (the st_dev field of struct
stat), in decimal.
.IP %f
-File's name with any leading directories removed (only the last element).
+Print the basename; the file's name with any leading directories
+removed (only the last element). For
+.BR /,
+the result is
+.BR /.
+See the
+.B EXAMPLES
+section for an example.
+
.IP %F
Type of the filesystem the file is on; this value can be used for
\-fstype.
@@ -1498,9 +1506,14 @@ File's group name, or numeric group ID if the group has no name.
.IP %G
File's numeric group ID.
.IP %h
-Leading directories of file's name (all but the last element).
-If the file name contains no slashes (since it is in the current
-directory) the %h specifier expands to `.'.
+Dirname; the Leading directories of the file's name (all but the last
+element). If the file name contains no slashes (since it is in the
+current directory) the %h specifier expands to `.'. For files which
+are themselves directories and contain a slash (including
+.BR /,
+), %h expands to the empty string. See the
+.B EXAMPLES
+section for an example.
.IP %H
Starting-point under which file was found.
.IP %i
@@ -2265,6 +2278,25 @@ find the first one:
.B find / -name needle -print -quit
.fi
+For some corner-cases, the interpretation of the
+.B %f
+and
+.B %h
+format directives of
+.B \-printf
+is not obvious. Here is an eample including some output.
+
+.nf
+.B $ find . .. / /tmp /tmp/TRACE compile compile/64/tests/find -maxdepth 0 -printf '[%h][%f]\en'
+.B [.][.]
+.B [.][..]
+.B [][/]
+.B [][tmp]
+.B [/tmp][TRACE]
+.B [.][compile]
+.B [compile/64/tests][find]
+.fi
+
.SH EXIT STATUS
.PP
.B find