From 263ed2e2a7692b4192b46416b9e559f26405b12f Mon Sep 17 00:00:00 2001 From: Schneems Date: Thu, 6 Jun 2024 16:21:12 -0500 Subject: [PATCH] Add doc hint that default is different than `tar` The default of `tar` is to include a symlink in the archive. The default of `tar::Builder` is to resolve symlinks and replace them with the resulting file. This commit helps to clarify that difference by highlighting that `follow_symlinks(true)` provides the same behavior as `tar -h`. ## Context This caused me much head-scratching in a problem where calling `tar` resulted in much lower file sizes than what I thought was the comparable rust code. I created a reproduction as part of that debugging process (if you're interested) https://github.com/schneems/tar_comparison/blob/bfd420a012b46e80435cf4e7c67ca1661357fde3/README.md. It turns out this was the issue I was facing: ``` $ tar -tvzf system_tar_gzip_one_operation.tar.gz | grep libruby.so -rwxr-xr-x 0 rschneeman staff 12364984 Jun 5 16:13 lib/libruby.so.3.1.6 lrwxr-xr-x 0 rschneeman staff 0 Jun 5 16:14 lib/libruby.so.3.1 -> libruby.so.3.1.6 lrwxr-xr-x 0 rschneeman staff 0 Jun 5 16:14 lib/libruby.so -> libruby.so.3.1.6 $ tar -tvzf rust_tar_gzip_one_operation.tar.gz | grep libruby.so -rwxr-xr-x 0 501 20 12364984 Jun 5 16:13 lib/libruby.so.3.1.6 -rwxr-xr-x 0 501 20 12364984 Jun 5 16:13 lib/libruby.so.3.1 -rwxr-xr-x 0 501 20 12364984 Jun 5 16:13 lib/libruby.so ``` In the "system" archive produced by the `tar` cli there's one `so` binary and two symlinks to the same file. In the "rust" version (using `tar::Builder`) there are three copies of the same binary. I previously saw that option's documentation when I was debugging my issue but didn't fully internalize the implications. My hope is that by documenting what feature this is similar to in (system) `tar`, that the reader will make a connection that the two have different defaults. --- src/builder.rs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/builder.rs b/src/builder.rs index a26eb31d..b786c5a4 100644 --- a/src/builder.rs +++ b/src/builder.rs @@ -40,6 +40,9 @@ impl Builder { /// Follow symlinks, archiving the contents of the file they point to rather /// than adding a symlink to the archive. Defaults to true. + /// + /// When true, it exhibits the same behavior as GNU `tar` command's + /// `--dereference` or `-h` options . pub fn follow_symlinks(&mut self, follow: bool) { self.follow = follow; }