version-sync 0.8.1

Simple crate for ensuring that version numbers in README files are updated when the crate version changes.

Keep your Version Numbers in Sync with Cargo.toml

Rust projects typically reference the crate version number in several places, such as the file. The version-sync crate makes it easy to add an integration test that checks that is updated when the crate version changes.


Add this to your Cargo.toml:

version-sync = "0.8"

Then create a tests/ file with:

fn test_readme_deps() {

fn test_html_root_url() {

This integration test will ensure that the dependencies mentioned in your file is kept in sync with your crate version and that your html_root_url points to the correct documentation on If everything is well, the test passes:

$ cargo test
    Finished debug [unoptimized + debuginfo] target(s) in 0.0 secs
     Running target/debug/deps/version_numbers-504f17c82f1defea

running 2 tests
test test_readme_deps ... ok
test test_html_root_url ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured

If the README or html_root_url is out of sync with the crate version, the tests fail. In this example, the version number in Cargo.toml has been changed to 0.2.0 while the and html_root_url remain unchanged. The tests now fail and the problematic TOML code and attribute are shown:

$ cargo test
    Finished debug [unoptimized + debuginfo] target(s) in 0.0 secs
     Running target/debug/deps/version_numbers-f399bac3e468d035

running 2 tests
test test_readme_deps ... FAILED
test test_html_root_url ... FAILED


---- test_readme_deps stdout ----
	Checking code blocks in (line 20) ... expected minor version 2, found 1 in
    version-sync = "0.1"

thread 'test_readme_deps' panicked at 'dependency errors in', tests/
note: Run with `RUST_BACKTRACE=1` for a backtrace.

---- test_html_root_url stdout ----
	Checking doc attributes in src/
src/ ... expected minor version 2, found 1 in
    #![doc(html_root_url = "")]

thread 'test_html_root_url' panicked at 'html_root_url errors in src/', tests/


test result: FAILED. 0 passed; 2 failed; 0 ignored; 0 measured

error: test failed

Excluding TOML Code

You can add no_sync to the language line in a code block to exclude it from the checks done by assert_markdown_deps_updated!:

your_crate = "0.1.2"

Release History

This is a changelog describing the most important changes per release.

Version 0.8.1 — April 3rd, 2019

Dependencies were relaxed to make it easier to upgrade version-sync.

Version 0.8.0 — March 28th, 2019

We now use Rust 2018, which means we require Rust version 1.31.0 or later. The assert_html_root_url_updated! macro will again report accurate line numbers based on span information from the syn crate.

Version 0.7.0 — January 14th, 2019

Special characters are now correctly escaped in the {name} and {version} placeholders in assert_contains_regex!.

Dependencies were updated and version-sync now requires Rust version 1.27.2 or later.

Version 0.6.0 — November 22nd, 2018

You can use assert_contains_regex! to grep files for the current version number. The search is done with a regular expression where {version} is replaced with the current version number.

Git dependencies are now always accepted, which means that blocks like

your_crate = { git = "..." }

will work without you having to add no_sync.

Issues closed:

  • #17: Allow to check non-markdown sources
  • #39: Version 0.5 requires Rust version 1.21.0
  • #42: Handle Git dependencies

Version 0.5.0 — November 19th, 2017

Dependencies were updated and version-sync now requires Rust version 1.21 or later.

Error messages from assert_html_root_url_updated! now again include line numbers (based on a heuristic until the syn crate can provide the information).

Version 0.4.0 — November 1st, 2017

This release replaces the dependency on the abandoned syntex_syntax with with a dependency on the much lighter syn crate. This improves compilation speed. Unfortunately, the syn crate does not provide information about line numbers, so error messages are are no longer as good. We might be able to work around that in a later version.

Version 0.3.1 — September 26th, 2017

This release fixes a small problem with the handling of pre-release identifiers.

Issues closed:

  • #19: Pre-release identifiers were ignored.

Version 0.3.0 — September 23rd, 2017

When checking dependencies in READMEs, TOML blocks can now be excluded from the check by adding no_sync to the language line:

your_crate = "0.1"

This TOML block will not be checked. This is similar to no_run for Rust code blocks.

Version 0.2.0 — September 20th, 2017

Added assert_html_root_url_updated! which will check that the html_root_url attribute points to the correct version of the crate documentation on

Version 0.1.3 — September 18th, 2017

First public release with support for finding outdated version numbers in dependencies and dev-dependencies.

Versions 0.1.0 to 0.1.2 were released under the name check-versions.


Version-sync can be distributed according to the MIT license. Contributions will be accepted under the same license.