Development environment#

poetry is a required package to develop.

$ git clone
$ cd libvcs
$ poetry install -E "docs test coverage lint format"

Makefile commands prefixed with watch_ will watch files and rerun.


$ poetry run py.test

Helpers: make test Rerun tests on file change: make watch_test (requires entr(1))


Default preview server: http://localhost:8068

sphinx-autobuild will automatically build the docs, watch for file changes and launch a server.

From home directory: make start_docs From inside docs/: make start

Manual documentation (the hard way)#

cd docs/ and make html to build. make serve to start http server.

Helpers: make build_docs, make serve_docs

Rebuild docs on file change: make watch_docs (requires entr(1))

Rebuild docs and run server via one terminal: make dev_docs (requires above, and a make(1) with -J support, e.g. GNU Make)


The project uses black and isort (one after the other). Configurations are in pyproject.toml and setup.cfg:

  • make black isort: Run black first, then isort to handle import nuances


flake8 and mypy run via CI in our GitHub Actions. See the configuration in pyproject.toml and setup.cfg.


flake8 provides fast, reliable, barebones styling and linting.


$ poetry run flake8

If you setup manually:

$ flake8
$ make flake8
$ make watch_flake8

requires entr(1).

See [flake8] in setup.cfg.

exclude = .*/,.tox,*.egg,libvcs/__*,
select = E,W,F,N
max-line-length = 88
# Stuff we ignore thanks to black:
ignore = E203,W503


mypy is used for static type checking.


$ poetry run mypy .

If you setup manually:

$ mypy .
$ make mypy
$ make watch_mypy

requires entr(1).


As of 0.10, poetry handles virtualenv creation, package requirements, versioning, building, and publishing. Therefore there is no or requirements files.

Update __version__ in and pyproject.toml::

git commit -m 'build(libvcs): Tag v0.1.1'
git tag v0.1.1
git push
git push --tags
poetry build
poetry publish