Skip to content

Commit

Permalink
Add doc hint that default is different than tar (#366)
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
schneems committed Jul 8, 2024
1 parent 2cb0c7b commit cdf5b6f
Showing 1 changed file with 3 additions and 0 deletions.
3 changes: 3 additions & 0 deletions src/builder.rs
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,9 @@ impl<W: Write> Builder<W> {

/// 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 <https://man7.org/linux/man-pages/man1/tar.1.html>.
pub fn follow_symlinks(&mut self, follow: bool) {
self.follow = follow;
}
Expand Down

0 comments on commit cdf5b6f

Please sign in to comment.