{"id":19320244,"url":"https://github.com/jlyonsmith/stampver-rs","last_synced_at":"2025-02-24T05:20:20.326Z","repository":{"id":57668542,"uuid":"402309324","full_name":"jlyonsmith/stampver-rs","owner":"jlyonsmith","description":"A tool for managing project version information","archived":false,"fork":false,"pushed_at":"2022-11-18T23:44:52.000Z","size":103,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-23T15:08:25.663Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jlyonsmith.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-09-02T06:07:16.000Z","updated_at":"2024-01-12T05:35:50.000Z","dependencies_parsed_at":"2023-01-23T14:00:07.958Z","dependency_job_id":null,"html_url":"https://github.com/jlyonsmith/stampver-rs","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlyonsmith%2Fstampver-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlyonsmith%2Fstampver-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlyonsmith%2Fstampver-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlyonsmith%2Fstampver-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jlyonsmith","download_url":"https://codeload.github.com/jlyonsmith/stampver-rs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240421526,"owners_count":19798585,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-10T01:27:58.720Z","updated_at":"2025-02-24T05:20:20.297Z","avatar_url":"https://github.com/jlyonsmith.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Version Stamping Tool (Rust Edition)\n\n[![coverage](https://shields.io/endpoint?url=https://raw.githubusercontent.com/jlyonsmith/stampver-rs/main/coverage.json)](https://github.com/jlyonsmith/stampver-rs/blob/main/coverage.json)\n[![Crates.io](https://img.shields.io/crates/v/stampver.svg)](https://crates.io/crates/stampver)\n[![Docs.rs](https://docs.rs/stampver/badge.svg)](https://docs.rs/stampver)\n\nA Rust package and command line tool for updating version information in ANY type of project.\n\n- Define which files need to be updated\n- Three types of actions; update in place, create or copy in existing files\n- Use regular expressions to find and replace content in existing files\n- Store and insert other information in addition to versions, such as copyrights, etc..\n- Fully customize the type of version update operations that you want for your project\n- Supports any type of versioning scheme that you wish to use\n\n## Overview\n\nReleasing a new project typically involves:\n\n- Updating version numbers in `package.json`, `Cargo.toml`, plus any source code files\n- Creating Git tags with version numbers\n- Building and ensuring all tests pass\n- Pushing changes to a cloud source repository, e.g. GitHub, GitLab, etc..\n- Publishing the newly minted and versioned package to a cloud package repository.\n\nAll of the above steps can be simplified with the use of this tool.\n\nTo use the tool for your project, simply:\n\n1. Place a `version.json5` file in your project root that:\n     - Describes the files that hold version numbers in your project\n     - Which of the three actions (update, write or copy-in) to perform on each file\n     - The types of version update operations you want to perform (`incrMajor`, `incrMinor`, etc..)\n2. Run `stampver` as part of your project's release script\n\nOnce you start using `stampver` you will be able to copy the `version.json5` file in from another project and tweak it slightly in order to get set up quickly.\n\n## Command Line\n\nThe command line tool `stampver` is included in this crate using the `cli` feature flag, which is installed by default.\n\n```text\nUSAGE:\n    stampver [OPTIONS] [OPERATION]\n\nARGS:\n    \u003cOPERATION\u003e    The versioning operation to perform\n\nOPTIONS:\n    -h, --help                  Print help information\n    -i, --input \u003cINPUT_FILE\u003e    Specify the version file explicitly\n    -u, --update                Actually do the update\n    -V, --version               Print version information\n```\n\nThe tool will describe the actions that it is taking on each file so you can check that it is doing what you expect.\n\n## Expressions\n\nThis package uses the [evalexpr](https://crates.io/crates/evalexpr) to provide the ability to customize the different calculations and operations.  All functions are available as described in the `evalexpr` *except* the `regex` functions. `stampver` adds the following variables/functions:\n\n| Identifier   | Argument Amount | Argument Types  | Description                                                              |\n| ------------ | --------------- | --------------- | ------------------------------------------------------------------------ |\n| `now::year`  | 0               |                 | Current UTC year                                                         |\n| `now::month` | 0               |                 | Current UTC month                                                        |\n| `now::day`   | 0               |                 | Current UTC day of the month                                             |\n| `if`         | 3               | Boolean/Any/Any | If expression `a` is `true` then the value of `b`, else the value of `c` |\n\n`stampver` uses the [Regex](https://crates.io/crates/regex) crate for regular expressions. You can use the amazing [Regex101](https://regex101.com/) site to develop and test your own regular expressions.  Use the PCRE2 flavor of regular expressions for the most compatability with the `Regex` crate.\n\n## Schema File Format\n\nHere's an annotated schema file format:\n\n```json5\n{\n  vars: {\n    major: 3,\n    minor: 0,\n    patch: 0,\n    build: 20210902,\n    revision: 0,\n    sequence: 6,\n    buildType: \"test\",\n    debug: true,\n  },\n  calcVars: {\n    nextBuild: \"now::year * 10000 + now::month * 100 + now::day\",\n    nextSequence: \"sequence + 1\",\n  },\n  operations: {\n    incrMajor: \"major += 1; minor = 0; patch = 0; revision = 0; build = nextBuild\",\n    incrMinor: \"minor += 1; patch = 0; revision = 0; build = nextBuild\",\n    incrPatch: \"patch += 1; revision = 0; build = nextBuild\",\n    incrRevision: \"revision += 1; build = nextBuild\",\n    incrSequence: \"sequence += 1\",\n    setBetaBuild: 'buildType = \"beta\"',\n    setProdBuild: 'buildType = \"prod\"',\n  },\n  targets: [\n    {\n      description: \"JavaScript Files\",\n      files: [\"src/version.js\"],\n      updates: [\n        {\n          search: '^(?P\u003cbegin\u003e\\\\s*export\\\\s*const\\\\s*version\\\\s*=\\\\s*\")\\\\d+\\\\.\\\\d+\\\\.\\\\d+(?P\u003cend\u003e\";?)$',\n          replace: 'begin + str::from(major) + \".\" + str::from(minor) + \".\" + str::from(patch) + end',\n        },\n        {\n          search: '^(?P\u003cbegin\u003e\\\\s*export\\\\s*const\\\\s*fullVersion\\\\s*=\\\\s*\")\\\\d+\\\\.\\\\d+\\\\.\\\\d+\\\\+\\\\d+\\\\.\\\\d+(?P\u003cend\u003e\";?)$',\n          replace: 'begin + str::from(major) + \".\" + str::from(minor) + \".\" + str::from(patch) + \"+\" + str::from(build) + \".\" + str::from(revision) + end',\n        },\n      ],\n    },\n    {\n      description: \"Git Version Tag\",\n      files: [\"scratch/version.tag.txt\"],\n      write: 'str::from(major) + \".\" + str::from(minor) + \".\" + str::from(patch)',\n    },\n    {\n      description: \"iOS PList\",\n      files: [\"some-file.plist\"],\n      copyFrom: '\"src/some-file\" + if(buildType == \"test\", \"-test\", \"-prod\") + \".plist\"',\n    },\n  ],\n}\n```\n\nBecause the format is [JSON5](https://json5.org/) and a superset of JSON you can freely use comments. It is recommended to use [Prettier](https://prettier.io/) or equivalent. This is not just to keep your file nicely formatted, but also because `stampver` needs to update the file it might get confused if the formatting is too different from the above.\n\nThe 4 main sections are as follows.\n\n### `vars`\n\nThis is where the version information lives, so in effect it is a simple version information database for you project.  This is also the only section that the tool rewrites when version information is updated.  It does it such a way as to preserve comments, but the tool does expect the layout to be like the example above.\n\n### `calcVars`\n\nThese are any variables that need to get generated each time the tool runs. This can include things like a `build` number that is based on the date, or a `nextSequence` number.  The values in this section are merged with the `vars`, so be wary of naming conflicts.\n\n### `operations`\n\nThese are the different version operations for your project. `incrMajor`, `incrMinor`, `incrPatch` are typical operations, but you can add whatever makes sense for your project.\n\n### `targets`\n\n`targets` is a array of objects containing a `description`, an array of `files` to update and then an action which must be exactly one of:\n\n- `updates` - An array of `{ search: , replace: }` objects.  `search` is a regular expression. It can contain at most two optional capture groups that **must be called** `begin` and `end`.  These can be used in the `replace` substitution string.\n- `write` - Writes content to the target files.  The content is an expression.\n- `copyFrom` - Copies a file from another file, relative to the location of the `version.json5` file.  The name of the other file is an expression.\n\n## License\n\nThis package is distributed under the terms of the [Unlicense](http://unlicense.org/) license. See the [`UNLICENSE`](UNLICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlyonsmith%2Fstampver-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjlyonsmith%2Fstampver-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlyonsmith%2Fstampver-rs/lists"}