stevedore - a side-project to help ignoring for Docker

I found out that some of my .dockerignore files where not entirely in the state I expected them. So I decided to make a command line tool to help me get an overview easily - introducing stevedore.

stevedore is currently an alpha version and there is still much work be done, but the tool is in a state that public scrutiny/review would be most welcome, so this is an invitation to provide some feedback on what is currently implemented and perhaps even what could be added in the future.

The primary use-case is to get your .dockerignore to match what you need for a given Docker based set up. In a directory containing a proposed Docker image, you can make a swift analysis of what is ignored and what is not.

If you already have .dockerignore file in the directory, you can simply do:

stevedore .

You can actually out the ., since stevedore defaults to the current directory.

If you have a .dockerignore file in another directory, you can either do:

cat /tmp/.dockerignore|stevedore --stdin .

Or:

stevedore --ignorefile /tmp/.dockerignore .

stevedore will emit all files encountered, with a minor exception that symbolic links are not followed. This is a limitation, which has bubbled up from the libraries on which stevedore is built, so there are no workarounds at this time.

This is an example run from the stevedore project directory.

The default output is colored for human interpretation, after all this is an analysis tool for a developer.

Here it is where it gets tricky. The question this tools aims to answer is:

What files have I ignored?

Files and directories not matched by the patterns/rules specified in the .dockerignore file are: red and files that are ignored are green. So the positive outcome, is actually what is handled (ignored) and vice-versa.

If this sort of the opposite of what you want, stevedore has a --invertcolors, which shift this around.

Alternatively you can provide two filters:

• --excluded (ignored)
• --included (not ignored)

Meaning you can request stevedore to only emit one or the other.

This is quite useful if you do not like the use of colors. You can disable use of colors with: --nocolor. If you want to do this without the command line arguments, you can set the environment variable: NO_COLOR.

stevedore attempts the balance between being useful for the main use case, making a basic report output, which are acting as a basic command line tool, so a .dockerignore file could be generated.

cat /tmp/.dockerignore | stevedore --stdin --included . >> .dockerignore

You do however have to review your .dockerignore file afterwards and boil it down to something more simple. A large .dockerignore file is not optimal, running stevedore consecutively will demonstrate this. So I plan to put some more work into giving the option of optimizing the output.

A little thing that I need to find a workaround for is handling of: ..

The basic output is very raw and can be used as is. But if you just request some more human friendly output, you can provide the argument: --verbose. Then stevedore emits more verbose output, not suited for command chaining, but for human consumption.

Example:

path README.md is not ignored and is included in Docker image

And of course stevedore has it's own ignore file, so you can create a .stevedoreignore, which can list patterns of files and directories you do not want stevedore to scan.

A basic example could look as follows:

.git

Which with the --verbose flag would emit:

.git have been ignored by stevedore, no traversal

And .git would not be a part of the output at when running without verbose, since the file would be ignored by stevedore and would be review for either inclusion or exclusion when doing the analysis.

This is the basic introduction to stevedore my little side-project.

You can get an overview all of the parameters here and there is more to come:

❯ ./stevedore --help
Usage of ./stevedore:
  -c    enable colors (default true)
  -color
        enable colors (default true)
  -debug
        emit debug messages
  -excluded
        only output excluded files
  -f    emits files and directories with full path (default true)
  -fullpath
        emits files and directories with full path (default true)
  -i string
        a path to an specific ignore file
  -ignorefile string
        a path to an specific ignore file
  -included
        only output included files
  -invertcolors
        inverts the used color
  -n    disable use of colors
  -nocolor
        disable use of colors
  -nofullpath
        emits files and directories without full path
  -s    read from ignore file from STDIN
  -stdin
        read from ignore file from STDIN
  -v    emit verbose output
  -verbose
        emit verbose output
  -x    only output excluded files

stevedore is open source and is available on GitHub, together with it's road map.

Currently the road map contains, quite a few suggestions:

• Ability to output a tree structure, for human readability
• Use of a configuration file, so often used command line options etc. can be specified globally
• Handling of stacked/nested ignore files
• An interactive edit mode for the proposed ignore file output
• Option for optimization of output

These are in no particular order, then will come when I have need them and I have the time to evaluate and possibly implement.

stevedore can be installed doing:

go install github.com/jonasbn/stevedore@latest

Comments, ideas, suggestions, bug report, PRs etc. most welcome.