Skip to content
😼 The madness vendoring utility for Golang programs
Go Shell Makefile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
tests
tree-examples
vendor remove unused vendors Dec 20, 2017
.gitignore
.gitmodules
.travis.yml
LICENSE
Makefile
README.md
handle_clean.go
handle_install.go
handle_query.go
handle_remove.go
handle_tree.go
handle_update.go
imports.go
main.go
submodule.go
utils.go

README.md

MANUL Build Status License Go Report Card

madness

Manul is a vendoring utility for Go programs.

Installation

manul can be obtained using go get:

go get github.com/kovetskiy/manul

Packages are also available for Ubuntu/Debian and Arch Linux.

What's the reason for yet another utility?

Because all other vendor utilities suffer from the following:

  • Some wrap the go binary and spoof the GOPATH env variable. You will have a non-go-gettable project which needs additional software in order to compile and run;

  • Some copy the source code of dependencies into the vendor directory:

    • It will be nearly impossible to find anything using GitHub Search, because you will get many false-positive results;
    • Updating dependencies will require manual intervention and committing a lot of modified lines straight into the main repo;
    • You will not be able to tell what version of dependency your project is using will by looking at repository; you have to keep versions in the additional ambiguous file with vendors associated with commits.
  • Various architecture problems:

    • Impossible to update all or specific vendored dependencies;
    • Impossible to rollback vendored dependencies to specific version;
    • Impossible to remove unused vendored dependencies;
    • Impossible to lock version of vendored dependency.

Solution

We all love git, it's a very powerful instrument. Why don't we use its power for vendoring dependencies using an awesome feature, which is called git submodule?

With git submodule you will have a git repository for each dependency. They can be managed in the same way as main project by git.

Pros:

  • No need for additional software for building/running your Go project;

  • No need for additional JSON/TOML/YAML file for storing dependencies;

  • Update vendored dependencies directly from remote origins;

  • Rollback changes in dependencies;

  • Go-gettable

git submodule might look like a Silver Bullet, but it's still clumsy to work with manually. We want to have a powerful yet simple interface for vendoring dependencies using this technology.

manul can do it for us.

Usage

Who needs a documentation when there are GIFs?

First of all, we should request dependencies which we have in our project. To do this, just run manul with -Q (query) flag. It will output all the project imports (dependencies), like this:

first query

For example, we have six dependencies, let's lock versions of critical dependencies by adding submodules: in our case it's zhash and blackfriday packages.

For locking versions (installing dependencies) we should use -I (install) flag and specify dependencies, which we wish to install:

install two dependencies

After installation we can have a look for vendored and non-vendored dependencies by using flag -Q. After previous step we should see git commits along with two already vendored dependencies (zhash and blackfriday):

query after install

Let's install submodules for remaining dependencies, go the limit! Just run manul with flag -I without specifying any dependencies, manul will install all detected dependencies with skipping already vendored:

install all dependencies

Wow, that was crazy! Now, to update some vendored dependencies, for example, docopt-go package, manul should be invoked with the flag -U and import path (github.com/docopt/docopt-go):

update docopt

manul can be used to remove specified submodules of vendored dependencies by using -R (remove) flag and specifying dependencies import path:

removing

By the way, manul can detect and remove unused vendored dependencies using -C (clean) flag:

unused dependencies

manul can also get you a specific version of a dependency by using a commit-ish, for example:

  • manul -I golang.org/x/foo=34a235h1 will install foo at the specified commit
  • manul -U github.com/x/bar=this-tag will update it to this-tag version.

Let's summarize:

  • -I [<dependency>...] - install git submodules for specified/all dependencies;
  • -U [<dependency>...] - update specified/all already vendored dependencies;
  • -R [<dependency>...] - remove git submodules for specified/all dependencies;
  • -Q [<dependency>...] - list all used dependencies;
  • -C - detect and remove all git submodules for unused vendored dependencies.

You can see similar help message by passing -h or --help flag.

You can’t perform that action at this time.