Docker Retag

🐳 Retag an existing Docker image without the overhead of pulling and pushing

Motivation

There are certain situation where it is desirable to give an existing Docker image an additional tag. This is usually acomplished by a docker pull, followed by a docker tag and a docker push.

That approach has the downside of downloading the contents of every layer from Docker Hub, which has bandwidth and performance implications, especially in a CI environment.

This tool uses the Docker Hub API to pull and push only a tiny manifest of the layers, bypassing the download overhead. Using this approach, an image of any size can be retagged in approximately 2 seconds.

Installing

From source

You can use go get to install this tool by running:

$ go get -u github.com/joshdk/docker-retag

Precompiled binary

Alternatively, you can download a static Linux release binary by running:

$ wget -q https://github.com/joshdk/docker-retag/releases/download/0.0.2/docker-retag
$ sudo install docker-retag /usr/bin

Usage

Setup

Since docker-retag communicates with the Docker Hub API, you must first export your account credentials into the working environment. These are the same credentials that you would use during docker login.

$ export DOCKER_USER='joshdk'
$ export DOCKER_PASS='hunter2'

The credentials must have both pull and push access for the Docker repository you are retagging.

Examples

This tool can be used in a few simple ways. The simplest of which is using a source image reference (similar to anything you could pass to docker tag) and a target tag.

Referencing a source image by tag name.

$ docker-retag joshdk/hello-world:1.0.0 1.0.1
  Retagged joshdk/hello-world:1.0.0 as joshdk/hello-world:1.0.1

Referencing a source image by sha256 digest.

$ docker-retag joshdk/hello-world@sha256:933f...3e90 1.0.1
  Retagged joshdk/hello-world@sha256:933f...3e90 as joshdk/hello-world:1.0.1

Referencing an image only by name will default to using latest.

$ docker-retag joshdk/hello-world 1.0.1
  Retagged joshdk/hello-world:latest as joshdk/hello-world:1.0.1

Additionally, you can pass the image name, source reference, and target tag as seperate arguments.

$ docker-retag joshdk/hello-world 1.0.0 1.0.1
  Retagged joshdk/hello-world:1.0.0 as joshdk/hello-world:1.0.1

$ docker-retag joshdk/hello-world @sha256:933f...3e90 1.0.1
  Retagged joshdk/hello-world@sha256:933f...3e90 as joshdk/hello-world:1.0.1

In all cases, the image and source reference must already exist in Docker Hub.

License

This library is distributed under the MIT License, see LICENSE.txt for more information.