minitar 1.1.0 → 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +94 -53
- data/CODE_OF_CONDUCT.md +155 -116
- data/CONTRIBUTING.md +154 -115
- data/LICENCE.md +8 -5
- data/Manifest.txt +2 -2
- data/README.md +20 -8
- data/Rakefile +7 -8
- data/SECURITY.md +16 -26
- data/lib/minitar/input.rb +243 -203
- data/lib/minitar/output.rb +69 -73
- data/lib/minitar/pax_header.rb +94 -94
- data/lib/minitar/posix_header.rb +273 -275
- data/lib/minitar/reader.rb +222 -222
- data/lib/minitar/version.rb +1 -1
- data/lib/minitar/writer.rb +247 -262
- data/lib/minitar.rb +97 -74
- data/test/test_path_normalization.rb +170 -0
- data/test/test_windows_extraction.rb +121 -0
- metadata +32 -25
- data/docs/bsdl.txt +0 -19
- data/docs/ruby.txt +0 -56
data/CONTRIBUTING.md
CHANGED
|
@@ -1,79 +1,124 @@
|
|
|
1
1
|
# Contributing
|
|
2
2
|
|
|
3
|
-
Contribution to
|
|
4
|
-
contributions.
|
|
3
|
+
Contribution to Minitar is encouraged: bug reports, feature requests, or code
|
|
4
|
+
contributions. New features should be proposed and discussed in an
|
|
5
|
+
[issue][issues].
|
|
5
6
|
|
|
6
|
-
|
|
7
|
+
Before contributing patches, please read the [Licence](./LICENCE.md).
|
|
7
8
|
|
|
8
|
-
|
|
9
|
-
or otherwise). I use [Standard Ruby][standardrb] for linting and formatting.
|
|
9
|
+
Minitar is governed under the [Contributor Covenant Code of Conduct][cccoc].
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
into logical chunks as necessary.
|
|
11
|
+
## Code Guidelines
|
|
13
12
|
|
|
14
|
-
|
|
15
|
-
merge strategy). Ensure that each commit includes the required Developer
|
|
16
|
-
Certificate of Origin [sign-off][sign-off].
|
|
13
|
+
I have several guidelines to contributing code through pull requests:
|
|
17
14
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
in the `CHANGELOG.md` and provide a link to your PR.)
|
|
15
|
+
- All code changes require tests. In most cases, this will be added or updated
|
|
16
|
+
unit tests. I use [Minitest][minitest].
|
|
21
17
|
|
|
22
|
-
|
|
23
|
-
|
|
18
|
+
- I use code formatters, static analysis tools, and linting to ensure
|
|
19
|
+
consistent styles and formatting. There should be no warning output from
|
|
20
|
+
test run processes. I use [Standard Ruby][standardrb].
|
|
24
21
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
present in alternative documentation generators.
|
|
22
|
+
- Proposed changes should be on a thoughtfully-named topic branch and
|
|
23
|
+
organized into logical commit chunks as appropriate.
|
|
28
24
|
|
|
29
|
-
-
|
|
25
|
+
- Use [Conventional Commits][conventional] with my
|
|
26
|
+
[conventions](#commit-conventions).
|
|
27
|
+
|
|
28
|
+
- Versions must not be updated in pull requests unless otherwise directed.
|
|
29
|
+
This means that you must not:
|
|
30
30
|
|
|
31
31
|
- Modify `VERSION` in `lib/minitar/version.rb`. When your patch is accepted
|
|
32
32
|
and a release is made, the version will be updated at that point.
|
|
33
33
|
|
|
34
34
|
- Modify `minitar.gemspec`; it is a generated file. (You _may_ use
|
|
35
|
-
`rake gemspec` to regenerate it if your change involves metadata related
|
|
36
|
-
gem itself).
|
|
35
|
+
`rake gemspec` to regenerate it if your change involves metadata related
|
|
36
|
+
to gem itself).
|
|
37
37
|
|
|
38
38
|
- Modify the `Gemfile`.
|
|
39
39
|
|
|
40
|
-
|
|
40
|
+
- Documentation should be added or updated as appropriate for new or updated
|
|
41
|
+
functionality. The documentation is RDoc; Minitar does not use extensions
|
|
42
|
+
that may be present in alternative documentation generators.
|
|
41
43
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
44
|
+
- All GitHub Actions checks marked as required must pass before a pull request
|
|
45
|
+
may be accepted and merged.
|
|
46
|
+
|
|
47
|
+
- Add your name or GitHub handle to `CONTRIBUTORS.md` and a record in the
|
|
48
|
+
`CHANGELOG.md` as a separate commit from your main change. (Follow the style
|
|
49
|
+
in the `CHANGELOG.md` and provide a link to your PR.)
|
|
46
50
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
51
|
+
- Include your DCO sign-off in each commit message (see
|
|
52
|
+
[LICENCE](LICENCE.md)).
|
|
53
|
+
|
|
54
|
+
## AI Contribution Policy
|
|
55
|
+
|
|
56
|
+
Minitar is a library that may have access to the underlying file system. It is
|
|
57
|
+
extremely important that contributions of any sort be well understood by the
|
|
58
|
+
submitter and that the developer can attest to the
|
|
59
|
+
[Developer Certificate of Origin][dco] for each pull request (see
|
|
60
|
+
[LICENCE](LICENCE.md)).
|
|
50
61
|
|
|
51
|
-
Any contribution (bug, feature request, or pull request) that uses
|
|
52
|
-
|
|
62
|
+
Any contribution (bug, feature request, or pull request) that uses undeclared
|
|
63
|
+
AI output will be rejected.
|
|
53
64
|
|
|
54
65
|
For an example of how this should be done, see [#151][pr-151] and its
|
|
55
66
|
[associated commits][pr-151-commits].
|
|
56
67
|
|
|
57
|
-
##
|
|
68
|
+
## Commit Conventions
|
|
69
|
+
|
|
70
|
+
Minitar has adopted a variation of the Conventional Commits format for commit
|
|
71
|
+
messages. The following types are permitted:
|
|
72
|
+
|
|
73
|
+
| Type | Purpose |
|
|
74
|
+
| ------- | ----------------------------------------------------- |
|
|
75
|
+
| `feat` | A new feature |
|
|
76
|
+
| `fix` | A bug fix |
|
|
77
|
+
| `chore` | A code change that is neither a bug fix nor a feature |
|
|
78
|
+
| `docs` | Documentation updates |
|
|
79
|
+
| `deps` | Dependency updates, including GitHub Actions. |
|
|
80
|
+
|
|
81
|
+
I encourage the use of [Tim Pope's][tpope-qcm] or [Chris Beam's][cbeams]
|
|
82
|
+
guidelines on the writing of commit messages
|
|
83
|
+
|
|
84
|
+
I require the use of [git][trailers1] [trailers][trailers2] for specific
|
|
85
|
+
additional metadata and strongly encourage it for others. The conditionally
|
|
86
|
+
required metadata trailers are:
|
|
87
|
+
|
|
88
|
+
- `Breaking-Change`: if the change is a breaking change. **Do not** use the
|
|
89
|
+
shorthand form (`feat!(scope)`) or `BREAKING CHANGE`.
|
|
58
90
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
tests in the same way that `rake test` does.
|
|
91
|
+
- `Signed-off-by`: this is required for all developers except me, as outlined
|
|
92
|
+
in the [Licence](./LICENCE.md#developer-certificate-of-origin).
|
|
62
93
|
|
|
63
|
-
|
|
94
|
+
- `Fixes` or `Resolves`: If a change fixes one or more open [issues][issues],
|
|
95
|
+
that issue must be included in the `Fixes` or `Resolves` trailer. Multiple
|
|
96
|
+
issues should be listed comma separated in the same trailer:
|
|
97
|
+
`Fixes: #1, #5, #7`, but _may_ appear in separate trailers. While both
|
|
98
|
+
`Fixes` and `Resolves` are synonyms, only _one_ should be used in a given
|
|
99
|
+
commit or pull request.
|
|
100
|
+
|
|
101
|
+
- `Related to`: If a change does not fix an issue, those issue references
|
|
102
|
+
should be included in this trailer.
|
|
103
|
+
|
|
104
|
+
## Testing Minitar
|
|
105
|
+
|
|
106
|
+
Minitar uses Ryan Davis's [Hoe][Hoe] to manage the release process, and it
|
|
107
|
+
adds a number of rake tasks. You will mostly be interested in `rake`, which
|
|
108
|
+
runs the tests the same way that `rake test` will do.
|
|
109
|
+
|
|
110
|
+
To assist with the installation of the development dependencies for Minitar, I
|
|
64
111
|
have provided the simplest possible Gemfile pointing to the (generated)
|
|
65
|
-
`minitar.gemspec` file. This will permit you to
|
|
66
|
-
|
|
112
|
+
`minitar.gemspec` file. This will permit you to do `bundle install` to get the
|
|
113
|
+
development dependencies.
|
|
67
114
|
|
|
68
115
|
You can run tests with code coverage analysis by running `rake coverage`.
|
|
69
116
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
methods that are useful for writing tests. These are maintained through modules
|
|
74
|
-
defined in `test/support`.
|
|
117
|
+
Minitar includes a number of custom test assertions, constants, and test
|
|
118
|
+
utility methods that are useful for writing tests. These are maintained
|
|
119
|
+
through modules defined in `test/support`.
|
|
75
120
|
|
|
76
|
-
|
|
121
|
+
### Fixture Utilities
|
|
77
122
|
|
|
78
123
|
Minitar uses fixture tarballs in various tests, referenced by their base name
|
|
79
124
|
(`test/fixtures/tar_input.tar.gz` becomes `tar_input`, etc.). There are two
|
|
@@ -87,19 +132,20 @@ utility methods:
|
|
|
87
132
|
`Zlib::GZipReader`. A block may be provided to ensure that the fixture is
|
|
88
133
|
automatically closed.
|
|
89
134
|
|
|
90
|
-
|
|
135
|
+
### Header Assertions and Utilities
|
|
91
136
|
|
|
92
137
|
Tar headers need to be built and compared in an exacting way, even for tests.
|
|
93
138
|
|
|
94
139
|
There are two assertions:
|
|
95
140
|
|
|
96
|
-
- `assert_headers_equal(expected, actual)`: This compares headers by field
|
|
97
|
-
verifying that each field in `actual` is supposed to match the
|
|
98
|
-
field in `expected`.
|
|
141
|
+
- `assert_headers_equal(expected, actual)`: This compares headers by field
|
|
142
|
+
order verifying that each field in `actual` is supposed to match the
|
|
143
|
+
corresponding field in `expected`.
|
|
99
144
|
|
|
100
145
|
`expected` must be a string representation of the expected header and this
|
|
101
146
|
assertion calls `#to_s` on the `actual` value so that both `PosixHeader` and
|
|
102
|
-
`PaxHeader` instances are converted to string representations for
|
|
147
|
+
`PaxHeader` instances are converted to string representations for
|
|
148
|
+
comparison.
|
|
103
149
|
|
|
104
150
|
- `assert_modes_equal(expected, actual, filename)`: This compares the expected
|
|
105
151
|
octal mode string of `expected` against `actual` for a given `filename`. The
|
|
@@ -107,9 +153,9 @@ There are two assertions:
|
|
|
107
153
|
|
|
108
154
|
There are several other helper methods available for working with headers:
|
|
109
155
|
|
|
110
|
-
- `build_tar_file_header(name, prefix, mode, length)`: This builds a header
|
|
111
|
-
a file `prefix/name` with `mode` and `length` bytes. `name` is limited
|
|
112
|
-
bytes and `prefix` is limited to 155 bytes.
|
|
156
|
+
- `build_tar_file_header(name, prefix, mode, length)`: This builds a header
|
|
157
|
+
for a file `prefix/name` with `mode` and `length` bytes. `name` is limited
|
|
158
|
+
to 100 bytes and `prefix` is limited to 155 bytes.
|
|
113
159
|
|
|
114
160
|
- `build_tar_dir_header(name, prefix, mode)`: This builds a header for a
|
|
115
161
|
directory `prefix/name` with `mode`. `name` is limited to 100 bytes and
|
|
@@ -119,28 +165,28 @@ There are several other helper methods available for working with headers:
|
|
|
119
165
|
for a symbolic link of `prefix/name` to `target` where the symbolic link has
|
|
120
166
|
`mode`. `name` is limited to 100 bytes and `prefix` is limited to 155 bytes.
|
|
121
167
|
|
|
122
|
-
- `build_tar_pax_header(name, prefix, bytes)`: This builds a header block for
|
|
123
|
-
PAX extension at `name/prefix` with `content_size` bytes.
|
|
168
|
+
- `build_tar_pax_header(name, prefix, bytes)`: This builds a header block for
|
|
169
|
+
a PAX extension at `name/prefix` with `content_size` bytes.
|
|
124
170
|
|
|
125
171
|
- `build_header(type, name, prefix, size, mode, link = "")`: This builds an
|
|
126
172
|
otherwise unspecified header type. If you find yourself using this, it is
|
|
127
173
|
recommended to add a new `build_*_header` helper method.
|
|
128
174
|
|
|
129
|
-
|
|
175
|
+
### Tarball Helpers
|
|
130
176
|
|
|
131
|
-
Minitar has several complex assertions and utilities to work with both
|
|
132
|
-
and on-disk tarballs. These work using two concepts, file hashes
|
|
133
|
-
and workspaces (`workspace`).
|
|
177
|
+
Minitar has several complex assertions and utilities to work with both
|
|
178
|
+
in-memory and on-disk tarballs. These work using two concepts, file hashes
|
|
179
|
+
(`file_hash`) and workspaces (`workspace`).
|
|
134
180
|
|
|
135
|
-
|
|
181
|
+
#### File Hashes (`file_hash`)
|
|
136
182
|
|
|
137
183
|
Many of these consume or produce a `file_hash`, which is a hash of
|
|
138
184
|
`{filename => content}` where the tarball will be produced with such that each
|
|
139
185
|
entry in the `file_hash` becomes a file named `filename` with the data
|
|
140
186
|
`content`.
|
|
141
187
|
|
|
142
|
-
As an example, `Minitar::TestHelpers` has a `MIXED_FILENAME_SCENARIOS`
|
|
143
|
-
that is a `file_hash`:
|
|
188
|
+
As an example, `Minitar::TestHelpers` has a `MIXED_FILENAME_SCENARIOS`
|
|
189
|
+
constant that is a `file_hash`:
|
|
144
190
|
|
|
145
191
|
```ruby
|
|
146
192
|
MIXED_FILENAME_SCENARIOS = {
|
|
@@ -164,53 +210,53 @@ nested/dir/y[108 more y' characters...]y.css
|
|
|
164
210
|
|
|
165
211
|
Each file will contain the text as the content.
|
|
166
212
|
|
|
167
|
-
If the `content` is `nil`, this will be ignored for in-memory tarballs, but
|
|
168
|
-
be created as empty directory entries for on-disk tarballs.
|
|
213
|
+
If the `content` is `nil`, this will be ignored for in-memory tarballs, but
|
|
214
|
+
will be created as empty directory entries for on-disk tarballs.
|
|
169
215
|
|
|
170
|
-
|
|
216
|
+
#### Workspace (`workspace`)
|
|
171
217
|
|
|
172
|
-
A workspace is a temporary directory used for on-disk tests. It is created
|
|
173
|
-
the `workspace` utility method (see below) and must be passed a block
|
|
174
|
-
setup and tests will be run.
|
|
218
|
+
A workspace is a temporary directory used for on-disk tests. It is created
|
|
219
|
+
with the `workspace` utility method (see below) and must be passed a block
|
|
220
|
+
where all setup and tests will be run.
|
|
175
221
|
|
|
176
222
|
At most one `workspace` may be used per test method.
|
|
177
223
|
|
|
178
|
-
|
|
224
|
+
#### Assertions
|
|
179
225
|
|
|
180
226
|
There are five assertions:
|
|
181
227
|
|
|
182
228
|
- `assert_tar_structure_preserved(original_files, extracted_files)`: This is
|
|
183
229
|
used primarily with string tarballs. Given two `file_hash`es representing
|
|
184
230
|
tarball contents (the original files passed to `create_tar_string` and the
|
|
185
|
-
extracted files returned from `extract_tar_string`), it ensures that all
|
|
186
|
-
from the original contents are present and that no additional files
|
|
187
|
-
added in the process.
|
|
231
|
+
extracted files returned from `extract_tar_string`), it ensures that all
|
|
232
|
+
files from the original contents are present and that no additional files
|
|
233
|
+
have been added in the process.
|
|
188
234
|
|
|
189
235
|
- `assert_files_extracted_in_workspace`: Can only be run in a `workspace` and
|
|
190
|
-
the test tarball must have been both created and extracted. This ensures
|
|
191
|
-
all of the files and/or directories expected have been extracted and
|
|
192
|
-
contents of files match. File modes are ignored for this assertion.
|
|
193
|
-
|
|
194
|
-
- `refute_file_path_duplication_in_workspace`: Can only be run in a `workspace`
|
|
195
|
-
and the test tarball must have been both created and extracted. This is used
|
|
196
|
-
to prevent regression of [#62][issue-62] with explicit file tests. This only
|
|
197
|
-
needs to be called after unpacking with Minitar methods.
|
|
236
|
+
the test tarball must have been both created and extracted. This ensures
|
|
237
|
+
that all of the files and/or directories expected have been extracted and
|
|
238
|
+
that the contents of files match. File modes are ignored for this assertion.
|
|
198
239
|
|
|
199
|
-
- `
|
|
240
|
+
- `refute_file_path_duplication_in_workspace`: Can only be run in a
|
|
200
241
|
`workspace` and the test tarball must have been both created and extracted.
|
|
201
|
-
This
|
|
202
|
-
|
|
203
|
-
|
|
242
|
+
This is used to prevent regression of [#62][issue-62] with explicit file
|
|
243
|
+
tests. This only needs to be called after unpacking with Minitar methods.
|
|
244
|
+
|
|
245
|
+
- `assert_extracted_files_match_source_files_in_workspace`: Can only be run in
|
|
246
|
+
a `workspace` and the test tarball must have been both created and
|
|
247
|
+
extracted. This ensures that there are no files missing or added in the
|
|
248
|
+
`target` directory that should are not also be in the `source` directory.
|
|
249
|
+
This does no contents comparison.
|
|
204
250
|
|
|
205
251
|
- `assert_file_modes_match_in_workspace`: Can only be run in a `workspace` and
|
|
206
|
-
the test tarball must have been both created and extracted. This ensures
|
|
207
|
-
all files have the same modes between source and target. This is
|
|
208
|
-
Windows.
|
|
252
|
+
the test tarball must have been both created and extracted. This ensures
|
|
253
|
+
that all files have the same modes between source and target. This is
|
|
254
|
+
skipped on Windows.
|
|
209
255
|
|
|
210
|
-
|
|
256
|
+
#### In-Memory Tarball Utilities
|
|
211
257
|
|
|
212
|
-
- `create_tar_string`: Given a `file_hash`, this creates a string containing
|
|
213
|
-
output of `Minitar::Output.open` and `Minitar.pack_as_file`.
|
|
258
|
+
- `create_tar_string`: Given a `file_hash`, this creates a string containing
|
|
259
|
+
the output of `Minitar::Output.open` and `Minitar.pack_as_file`.
|
|
214
260
|
|
|
215
261
|
- `extract_tar_string`: Given the string output of `create_tar_string` (or any
|
|
216
262
|
uncompressed tarball string), uses `Minitar::Input.open` to read the files
|
|
@@ -219,55 +265,48 @@ There are five assertions:
|
|
|
219
265
|
- `roundtrip_tar_string`: calls `create_tar_string` on a `file_hash` and
|
|
220
266
|
immediately calls `extract_tar_string`, returning a processed `file_hash`.
|
|
221
267
|
|
|
222
|
-
|
|
268
|
+
#### On-Disk Workspace Tarball Utilities
|
|
223
269
|
|
|
224
|
-
- `workspace`: Prepares a temporary directory for working with tarballs on
|
|
225
|
-
inside the block that must be provided. If given a hash of files, calls
|
|
270
|
+
- `workspace`: Prepares a temporary directory for working with tarballs on
|
|
271
|
+
disk inside the block that must be provided. If given a hash of files, calls
|
|
226
272
|
`prepare_files`. The workspace directory will be removed after the block
|
|
227
273
|
finishes executing.
|
|
228
274
|
|
|
229
|
-
A workspace has a `source` directory, a `target`
|
|
230
|
-
which will be created from the prepared files.
|
|
275
|
+
A workspace has a `source` directory, a `target`
|
|
276
|
+
directory`, and the`tarball` which will be created from the prepared files.
|
|
231
277
|
|
|
232
278
|
All other utility methods _must_ be run inside of a `workspace` block.
|
|
233
279
|
|
|
234
280
|
- `prepare_workspace`: creates a file structure in the workspace source
|
|
235
|
-
directory given the `{filename => content}` hash. For on-disk file
|
|
236
|
-
`{directory_name => nil}` can be used to create empty
|
|
237
|
-
names will be created automatically for nested
|
|
281
|
+
directory given the `{filename => content}` hash. For on-disk file
|
|
282
|
+
structures, `{directory_name => nil}` can be used to create empty
|
|
283
|
+
directories. Directory names will be created automatically for nested
|
|
284
|
+
filenames.
|
|
238
285
|
|
|
239
286
|
- `gnu_tar_create_in_workspace`, `gnu_tar_extract_in_workspace`, and
|
|
240
287
|
`gnu_tar_list_in_workspace` work with the workspace tarball using GNU tar
|
|
241
288
|
(either `tar` or `gtar`). GNU tar tests will be skipped if GNU tar is not
|
|
242
289
|
available.
|
|
243
290
|
|
|
244
|
-
- `minitar_pack_in_workspace`, `minitar_unpack_in_workspace` use
|
|
245
|
-
and `Minitar.unpack`, respectively, to work with the
|
|
291
|
+
- `minitar_pack_in_workspace`, `minitar_unpack_in_workspace` use
|
|
292
|
+
`Minitar.pack` and `Minitar.unpack`, respectively, to work with the
|
|
293
|
+
workspace tarball.
|
|
246
294
|
|
|
247
295
|
- `minitar_writer_create_in_workspace` uses `Minitar::Writer` to create the
|
|
248
296
|
workspace tarball.
|
|
249
297
|
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
- Fork the project.
|
|
255
|
-
- Clone your fork (`git clone git://github.com/<username>/minitar.git`).
|
|
256
|
-
- Create a topic branch to contain your change
|
|
257
|
-
(`git checkout -b my_awesome_feature`).
|
|
258
|
-
- Hack away, add tests. Not necessarily in that order.
|
|
259
|
-
- Make sure everything still passes by running `rake`.
|
|
260
|
-
- If necessary, rebase your commits into logical chunks, without errors.
|
|
261
|
-
- Push the branch up (`git push origin my_awesome_feature`).
|
|
262
|
-
- Create a pull request against halostatue/minitar and describe what your change
|
|
263
|
-
does and the why you think it should be merged.
|
|
264
|
-
|
|
298
|
+
[cbeams]: https://cbea.ms/git-commit/
|
|
299
|
+
[cccoc]: ./CODE_OF_CONDUCT.md
|
|
300
|
+
[conventional]: https://www.conventionalcommits.org/en/v1.0.0/
|
|
265
301
|
[dco]: licences/dco.txt
|
|
266
302
|
[hoe]: https://github.com/seattlerb/hoe
|
|
267
303
|
[issue-62]: https://github.com/halostatue/minitar/issues/62
|
|
304
|
+
[issues]: https://github.com/halostatue/minitar/issues
|
|
268
305
|
[minitest]: https://github.com/seattlerb/minitest
|
|
269
306
|
[pr-151-commits]: https://github.com/halostatue/minitar/pull/151/commits
|
|
270
307
|
[pr-151]: https://github.com/halostatue/minitar/pull/151
|
|
271
|
-
[qcm]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
|
|
272
308
|
[sign-off]: LICENCE.md#developer-certificate-of-origin
|
|
273
309
|
[standardrb]: https://github.com/standardrb/standard
|
|
310
|
+
[tpope-qcm]: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
|
|
311
|
+
[trailers1]: https://git-scm.com/docs/git-interpret-trailers
|
|
312
|
+
[trailers2]: https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---trailerlttokengtltvaluegt
|
data/LICENCE.md
CHANGED
|
@@ -1,12 +1,14 @@
|
|
|
1
1
|
# Licence
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<-- SPDX-License-Identifier: Ruby or BSD-2-clause -->
|
|
4
|
+
|
|
5
|
+
- Copyright 2004–2026 Austin Ziegler and other contributors.
|
|
6
|
+
- Portions copyright 2004 Mauricio Julio Fernández Pradier.
|
|
4
7
|
|
|
5
8
|
minitar is free software that may be redistributed and/or modified under the
|
|
6
9
|
terms of Ruby’s licence or the Simplified BSD licence.
|
|
7
10
|
|
|
8
|
-
-
|
|
9
|
-
- Portions copyright 2004 Mauricio Julio Fernández Pradier.
|
|
11
|
+
- SPDX License: [Ruby][ruby-license] OR [BSD-2-Clause][bsd-2-clause]
|
|
10
12
|
|
|
11
13
|
### Simplified BSD Licence
|
|
12
14
|
|
|
@@ -19,8 +21,9 @@ See the file [ruby.txt](docs/ruby.txt) in the main distribution.
|
|
|
19
21
|
## Developer Certificate of Origin
|
|
20
22
|
|
|
21
23
|
All contributors **must** certify they are willing and able to provide their
|
|
22
|
-
contributions under the terms of this project's licences with the
|
|
23
|
-
of the
|
|
24
|
+
contributions under the terms of this project's licences with the
|
|
25
|
+
certification of the
|
|
26
|
+
[Developer Certificate of Origin (Version 1.1)](licences/dco.txt).
|
|
24
27
|
|
|
25
28
|
Such certification is provided by ensuring that a `Signed-off-by`
|
|
26
29
|
[commit trailer][trailer] is present on every commit:
|
data/Manifest.txt
CHANGED
|
@@ -7,8 +7,6 @@ Manifest.txt
|
|
|
7
7
|
README.md
|
|
8
8
|
Rakefile
|
|
9
9
|
SECURITY.md
|
|
10
|
-
docs/bsdl.txt
|
|
11
|
-
docs/ruby.txt
|
|
12
10
|
lib/minitar.rb
|
|
13
11
|
lib/minitar/input.rb
|
|
14
12
|
lib/minitar/output.rb
|
|
@@ -38,6 +36,7 @@ test/test_integration_pack_unpack_cycle.rb
|
|
|
38
36
|
test/test_issue_46.rb
|
|
39
37
|
test/test_issue_62.rb
|
|
40
38
|
test/test_minitar.rb
|
|
39
|
+
test/test_path_normalization.rb
|
|
41
40
|
test/test_pax_header.rb
|
|
42
41
|
test/test_pax_support.rb
|
|
43
42
|
test/test_tar_header.rb
|
|
@@ -45,3 +44,4 @@ test/test_tar_input.rb
|
|
|
45
44
|
test/test_tar_output.rb
|
|
46
45
|
test/test_tar_reader.rb
|
|
47
46
|
test/test_tar_writer.rb
|
|
47
|
+
test/test_windows_extraction.rb
|
data/README.md
CHANGED
|
@@ -1,16 +1,21 @@
|
|
|
1
1
|
# minitar
|
|
2
2
|
|
|
3
|
+
[![RubyGems Version][shield-gems]][rubygems] ![Coveralls][shield-coveralls]
|
|
4
|
+
[![Build Status][shield-ci]][ci-workflow]
|
|
5
|
+
|
|
3
6
|
- code :: <https://github.com/halostatue/minitar>
|
|
4
7
|
- issues :: <https://github.com/halostatue/minitar/issues>
|
|
8
|
+
- docs :: <https://halostatue.github.io/minitar/>
|
|
5
9
|
- changelog :: <https://github.com/halostatue/minitar/blob/main/CHANGELOG.md>
|
|
6
10
|
|
|
7
11
|
## Description
|
|
8
12
|
|
|
9
|
-
The minitar library is a pure-Ruby library that operates on POSIX tar(1)
|
|
10
|
-
files.
|
|
13
|
+
The minitar library is a pure-Ruby library that operates on POSIX tar(1)
|
|
14
|
+
archive files.
|
|
11
15
|
|
|
12
16
|
minitar (previously called Archive::Tar::Minitar) is based heavily on code
|
|
13
|
-
originally written by Mauricio Julio Fernández Pradier for the rpa-base
|
|
17
|
+
originally written by Mauricio Julio Fernández Pradier for the rpa-base
|
|
18
|
+
project.
|
|
14
19
|
|
|
15
20
|
## Synopsis
|
|
16
21
|
|
|
@@ -39,9 +44,9 @@ A gzipped tar can be written with:
|
|
|
39
44
|
```
|
|
40
45
|
|
|
41
46
|
As the case above shows, one need not write to a file. However, it will
|
|
42
|
-
sometimes require that one dive a little deeper into the API, as in the case
|
|
43
|
-
StringIO objects. Note that I'm not providing a block with Minitar::Output,
|
|
44
|
-
Minitar::Output#close automatically closes both the Output object and the
|
|
47
|
+
sometimes require that one dive a little deeper into the API, as in the case
|
|
48
|
+
of StringIO objects. Note that I'm not providing a block with Minitar::Output,
|
|
49
|
+
as Minitar::Output#close automatically closes both the Output object and the
|
|
45
50
|
wrapped data stream object.
|
|
46
51
|
|
|
47
52
|
```ruby
|
|
@@ -63,8 +68,15 @@ See [SECURITY](./SECURITY.md)
|
|
|
63
68
|
|
|
64
69
|
## minitar Semantic Versioning
|
|
65
70
|
|
|
66
|
-
The minitar library uses a [Semantic Versioning][semver] scheme with one
|
|
71
|
+
The minitar library uses a [Semantic Versioning][semver] scheme with one
|
|
72
|
+
change:
|
|
67
73
|
|
|
68
74
|
- When PATCH is zero (`0`), it will be omitted from version references.
|
|
69
75
|
|
|
70
|
-
[
|
|
76
|
+
[ci-workflow]: https://github.com/halostatue/minitar/actions/workflows/ci.yml
|
|
77
|
+
[coveralls]: https://coveralls.io/github/halostatue/minitar?branch=main
|
|
78
|
+
[rubygems]: https://rubygems.org/gems/minitar
|
|
79
|
+
[semver]: https://semver.org/
|
|
80
|
+
[shield-ci]: https://img.shields.io/github/actions/workflow/status/halostatue/minitar/ci.yml?style=for-the-badge "Build Status"
|
|
81
|
+
[shield-coveralls]: https://img.shields.io/coverallsCoverage/github/halostatue/minitar?style=for-the-badge
|
|
82
|
+
[shield-gems]: https://img.shields.io/gem/v/minitar?style=for-the-badge "Version"
|
data/Rakefile
CHANGED
|
@@ -8,7 +8,6 @@ require "minitest"
|
|
|
8
8
|
require "minitest/test_task"
|
|
9
9
|
|
|
10
10
|
Hoe.plugin :halostatue
|
|
11
|
-
Hoe.plugin :rubygems
|
|
12
11
|
|
|
13
12
|
Hoe.plugins.delete :debug
|
|
14
13
|
Hoe.plugins.delete :newb
|
|
@@ -30,14 +29,14 @@ hoe = Hoe.spec "minitar" do
|
|
|
30
29
|
}
|
|
31
30
|
|
|
32
31
|
extra_dev_deps << ["hoe", "~> 4.0"]
|
|
33
|
-
extra_dev_deps << ["hoe-halostatue", "~>
|
|
32
|
+
extra_dev_deps << ["hoe-halostatue", "~> 3.0"]
|
|
34
33
|
extra_dev_deps << ["irb", "~> 1.0"]
|
|
35
|
-
extra_dev_deps << ["minitest", "
|
|
34
|
+
extra_dev_deps << ["minitest", ">= 5.16", "< 7"]
|
|
36
35
|
extra_dev_deps << ["minitest-autotest", "~> 1.0"]
|
|
37
36
|
extra_dev_deps << ["minitest-focus", "~> 1.1"]
|
|
38
37
|
extra_dev_deps << ["rake", ">= 10.0", "< 14"]
|
|
39
|
-
extra_dev_deps << ["rdoc", ">= 0.0", "<
|
|
40
|
-
extra_dev_deps << ["simplecov", "
|
|
38
|
+
extra_dev_deps << ["rdoc", ">= 0.0", "< 8"]
|
|
39
|
+
extra_dev_deps << ["simplecov", ">= 0.22", "< 2"]
|
|
41
40
|
extra_dev_deps << ["simplecov-lcov", "~> 0.8"]
|
|
42
41
|
extra_dev_deps << ["standard", "~> 1.0"]
|
|
43
42
|
extra_dev_deps << ["standard-minitest", "~> 1.0"]
|
|
@@ -73,13 +72,13 @@ end
|
|
|
73
72
|
task default: :test
|
|
74
73
|
|
|
75
74
|
task :version do
|
|
76
|
-
require "
|
|
77
|
-
puts
|
|
75
|
+
require "minitar/version"
|
|
76
|
+
puts Minitar::VERSION
|
|
78
77
|
end
|
|
79
78
|
|
|
80
79
|
RDoc::Task.new do
|
|
81
80
|
_1.title = "minitar"
|
|
82
|
-
_1.main = "
|
|
81
|
+
_1.main = "README.md"
|
|
83
82
|
_1.rdoc_dir = "doc"
|
|
84
83
|
_1.rdoc_files = hoe.spec.require_paths - ["Manifest.txt"] + hoe.spec.extra_rdoc_files
|
|
85
84
|
_1.markup = "markdown"
|
data/SECURITY.md
CHANGED
|
@@ -4,41 +4,32 @@ Minitar aims to be secure by default for the data _inside_ of a tar file.
|
|
|
4
4
|
|
|
5
5
|
## LLM-Generated Security Report Policy
|
|
6
6
|
|
|
7
|
-
Absolutely no security reports will be accepted that have been generated
|
|
8
|
-
agents.
|
|
7
|
+
Absolutely no security reports will be accepted that have been generated
|
|
8
|
+
solely by LLM agents. There must be a human that confirms the issue.
|
|
9
9
|
|
|
10
10
|
## Supported Versions
|
|
11
11
|
|
|
12
|
-
Security reports are accepted only for the most recent major release.
|
|
13
|
-
December 2024, that is the 1.0 release series. Older releases are no longer
|
|
14
|
-
supported.
|
|
12
|
+
Security reports are accepted only for the most recent major release.
|
|
15
13
|
|
|
16
14
|
## Reporting a Vulnerability
|
|
17
15
|
|
|
18
|
-
|
|
19
|
-
coordinate the fix and disclosure.
|
|
16
|
+
Report vulnerabilities via the [Tidelift security contact][tidelift]. Tidelift
|
|
17
|
+
will coordinate the fix and disclosure.
|
|
20
18
|
|
|
21
|
-
Alternatively,
|
|
22
|
-
`Minitar` in the subject. Emails sent to this address should be encrypted using
|
|
23
|
-
[age][age] with the following public key:
|
|
24
|
-
|
|
25
|
-
```
|
|
26
|
-
age1fc6ngxmn02m62fej5cl30lrvwmxn4k3q2atqu53aatekmnqfwumqj4g93w
|
|
27
|
-
```
|
|
19
|
+
Alternatively, create a [private vulnerability report][advisory] with GitHub.
|
|
28
20
|
|
|
29
21
|
## Exclusions
|
|
30
22
|
|
|
31
|
-
There are several classes of potential security issues that will not be
|
|
32
|
-
for Minitar
|
|
33
|
-
|
|
34
|
-
library being used incorrectly.
|
|
23
|
+
There are several classes of potential security issues that will **not** be
|
|
24
|
+
accepted for Minitar, because any issues arising from these are a matter of
|
|
25
|
+
the library being used incorrectly.
|
|
35
26
|
|
|
36
27
|
- [CWE-073](https://cwe.mitre.org/data/definitions/73.html)
|
|
37
28
|
- [CWE-078](https://cwe.mitre.org/data/definitions/78.html)
|
|
38
29
|
- [CWE-088](https://cwe.mitre.org/data/definitions/88.html)
|
|
39
30
|
|
|
40
|
-
Minitar does _not_ perform validation or sanitization of path names provided
|
|
41
|
-
the convenience classes `Minitar::Output` and `Minitar::Input`, which use
|
|
31
|
+
Minitar does _not_ perform validation or sanitization of path names provided
|
|
32
|
+
to the convenience classes `Minitar::Output` and `Minitar::Input`, which use
|
|
42
33
|
`Kernel.open` for their underlying implementations when not given an IO-like
|
|
43
34
|
object.
|
|
44
35
|
|
|
@@ -49,16 +40,15 @@ starts with the pipe character (`|`), the command following the pipe character
|
|
|
49
40
|
is executed.
|
|
50
41
|
|
|
51
42
|
Additionally, the use of the `open-uri` library (which extends `Kernel.open`
|
|
52
|
-
with transparent implementations
|
|
53
|
-
there are other possible vulnerabilities when accepting arbitrary
|
|
54
|
-
[detailed][openuri] by Egor Homakov.
|
|
43
|
+
with transparent implementations for `Net::HTTP`, `Net::HTTPS`, and
|
|
44
|
+
`Net::FTP`), there are other possible vulnerabilities when accepting arbitrary
|
|
45
|
+
input, as [detailed][openuri] by Egor Homakov.
|
|
55
46
|
|
|
56
47
|
These security vulnerabilities may be avoided, even with the `Minitar::Output`
|
|
57
48
|
and `Minitar::Input` convenience classes, by providing IO-like objects instead
|
|
58
49
|
of pathname-like objects as the source or destination of these classes.
|
|
59
50
|
|
|
60
|
-
[tidelift]: https://tidelift.com/security
|
|
61
|
-
[email]: mailto:minitar@halostatue.ca
|
|
62
|
-
[age]: https://github.com/FiloSottile/age
|
|
63
51
|
[CVE-2017-17405]: https://nvd.nist.gov/vuln/detail/CVE-2017-17405
|
|
52
|
+
[advisory]: https://github.com/halostatue/diff-lcs/security/advisories/new
|
|
64
53
|
[openuri]: https://sakurity.com/blog/2015/02/28/openuri.html
|
|
54
|
+
[tidelift]: https://tidelift.com/security
|