stevedore - a side-project to help ignoring for Docker
Tags: sideprojects, docker, opensource, stevedore
Published: 2023-02-07 16:53:02

---
title: stevedore - a side-project to help ignoring for Docker
published: true
description: a little command line tool for analyzing your .dockerignore file
tags: sideproject, docker, opensource, stevedore
# cover_image: https://direct_url_to_image.jpg
# Use a ratio of 100:42 for best results.
# published_at: 2023-02-07 16:45 +0000
---
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:

```shell
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:

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

Or:

```shell
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](https://github.com/jonasbn/stevedore).

![Screenshot of stevedore terminal output](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2ibi45oh0elo18g86pa8.png)

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.

```shell
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:

```shell
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:

```shell
.git
```

Which with the `--verbose` flag would emit:

```shell
.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:

```shell
❯ ./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](https://github.com/jonasbn/stevedore), together with it's [road map](https://github.com/jonasbn/stevedore/issues).

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:

```shell
go install github.com/jonasbn/stevedore@latest
```

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