CLI and NodeJS utility for packing files based on ignore glob pattern lists, such as .gitignore files.

Use it with / without installing:

npx globlist-packer

For frequent use, you should really install the package:

# Globally
npm i -g globlist-packer

# Local devDependency
npm i -D globlist-packer

Once it is installed, it also exposes two callable names (through .bin)

globlist-packer

# Or

globpack

🚨 Warning: Ignore glob lists, such as .gitignore, work by either negating, or reversing a previous negation. Meaning, by default all files are included, unless they match a pattern in an ignore list. If you are new to git, or this concept, you might find these docs (Atlassian, git-scm) helpful.

Despite the number of configurable options, this tool is designed to be "zero-config", and can work out-of-the-box with minimal settings, for the majority of use-cases.

For example, if you are working with git and wanted to pack your current repo directory to an archive, while keeping files out that are ignored by .gitignore, it should be possible with just:

npx globlist-packer

Or, if you want a specific globlist to be used:

# This will create `dist.zip` in same directory, based on glob(s) contained in `dist.ignorelist`
npx globlist-packer -i dist.ignorelist

You can also use it via JS / TS, by installing the package and then importing:

// ESM import
import {GloblistPacker} from 'globlist-packer';

GloblistPacker({
	ignoreListFileNames: ['dist.ignorelist'],
	// This will create `distribution.zip`
	archiveName: 'distribution',
	archiveType: 'zip'
});

For more advanced uses, see options below, and examples under "Usage Examples".

As much as possible, I try to make all options and flags available through both the main JS entry-point, as well as through the CLI. Refer to the table below, the source code, or use --help with the CLI.

The following options are only available when calling the program via JS/TS.

Example scenario(s):

.
├── package-lock.json
├── package.json
├── README.md
├── build/
│   ├── index.html
│   ├── index.js
│   └── style.css
├── src/
│   ├── index.js
│   └── style.css
├── vendor/
│   └── vendor-bundle.js
├── node_modules/
│   └── ... (lots of files)
└── tests/
    └── ... (lots of files)

node_modules
build
vendor

# Remove all source code, and unneeded files
src
tests
package-lock.json
package.json

# Block recursive packing if ran again
dist.tgz
dist.zip

# OVERRIDE ignores in .gitignore, adding back build files and artifacts
!build
!vendor

globlist-packer -i dist.packlistignore

This is semi-experimental, as it is not the main intended use of the program, but for convenience I have added an option that lets you use this to only copy files (based on globlists) to a target directory, and skip the archive / tar / zip generation.

To use this feature, pass a string to the copy-files-to option (or copyFilesTo via JS API) - this will cause the tool to skip all archiver steps and only handle copying files. You can still use all the input control options (such as ignorelist-files, include-default-ignores, etc.).

The truth is that this feature complicates things a little bit. For example, if the target output directory is nested inside the root directory, then I have to block files that live inside the output directory, to prevent recursive copying in case the tool is ran more than once without clearing the output.

This tool is primarily a wrapper around the ignore-walk package. Due to some limitations in that package, and complexities of resolving glob patterns (remember: you can have negation in glob lists), if the includeDefaultIgnores option is true (which is default), this tool will actually temporarily inject a ignore glob list file in your project root directory.

Multiple considerations are taken around this action:

• The file only exists for as long as it takes to walk the file tree. This can be as short as milliseconds.
• The file is given a long and dynamic filename - highly unlikely to collide with any existing files
  • If, somehow, a file already exists with that name, the program will halt and not overwrite the existing file

If includeDefaultIgnores is set to true, which is also the default value, then a few default ignore patterns are added to prevent unwanted files from ending up in the packing process.

As of writing this, the default ignore patterns are node_modules and .git, but you can browse ./src to see for yourself.

Of course, after building this tool I immediately found some that might have fit the bill for what I needed. However, all of these are slightly different from what this tool offers:

• palletjack
• gitzip