From: Karl Berry <karl@freefriends.org>
Date: Sun, 23 Feb 2025 18:38:57 +0000 (-0800)
Subject: doc: tar-pax also works around too-large uid/gid for tar.
X-Git-Tag: v1.17.90~9
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=de96135b0dadbc2d8d58b697a228cf2166ba5084;p=thirdparty%2Fautomake.git

doc: tar-pax also works around too-large uid/gid for tar.

From https://bugs.gnu.org/73316.

* doc/automake.texi (Basics of Distribution): also mention
the tar-pax format as a fix for out of range uid/gid for tar.
---

diff --git a/doc/automake.texi b/doc/automake.texi
index bb66aea5c..b520880c5 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -8854,10 +8854,13 @@ archives.
 @vindex TAR_OPTIONS
 With GNU tar, you can also set the environment (or @code{Makefile.am})
 variable @code{TAR_OPTIONS} to pass options to @code{tar}.  One common
-case for this is wanting to avoid using the local user's uid and gid
-in the tar file, or the uid being larger than is supported by the tar
-format (not uncommon nowadays). This can be done with, for example>
+case for using this is to avoid having the local user's uid and gid in
+the tar file, or the uid being larger than is supported by the tar
+format. This can be done with, for example:
 
+@cindex tar uid/gid setting
+@cindex uid/gid, setting for tar
+@cindex too-large uid/gid for tar
 @example
 TAR_OPTIONS = --owner=0 --group=0
 export TAR_OPTIONS
@@ -8865,8 +8868,11 @@ export TAR_OPTIONS
 
 @noindent
 The @code{export} (a GNU make feature) is necessary to pass the
-variable in the environment to the @code{tar} invocation.
-(For more discussion, see @url{https://bugs.gnu.org/19615}.)
+variable in the environment to the @code{tar} invocation. Another
+possible fix is to use the @code{tar-pax} option
+(@pxref{tar-formats}), though this reduces portability.
+(For more discussion, see @url{https://bugs.gnu.org/19615}
+and @url{https://bugs.gnu.org/73316}.)
 
 For the most part, the files to distribute are automatically
 found by Automake:
@@ -11378,8 +11384,8 @@ shorter than 256 characters.
 
 @option{tar-pax} selects the new pax interchange format defined by POSIX
 1003.1-2001.  It does not limit the length of file names.  However,
-this format is very young and should probably be restricted to
-packages that target only very modern platforms.
+this format is relatively young and should probably be restricted to
+packages that target modern platforms.
 As of 2018, this format is supported by the native @code{tar} command only
 on GNU, FreeBSD, and OpenBSD systems; it is not supported by the native
 @code{tar} command on NetBSD, AIX, HP-UX, or Solaris.