# build-revision

> Generate semver compatible version to uniquely identify project build using build metadata

Latest version **4.1.2** (published 2021-07-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install build-revision
pnpm add build-revision
yarn add build-revision
bun add build-revision
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.1.2 |
| Published | 2021-07-10 |
| First published | 2017-02-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 9.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Abhishek Dev |
| Maintainers | abhishekdev |
| Keywords | build, version, revision, hash, SHA |

## Links

- npm: https://www.npmjs.com/package/build-revision
- Repository: https://github.com/abhishekdev/build-revision
- Homepage: https://github.com/abhishekdev/build-revision#readme
- Issues: https://github.com/abhishekdev/build-revision/issues
- npm.io page: https://npm.io/package/build-revision

## Dependencies (4)

- [dayjs](https://npm.io/package/dayjs.md) ^1.10.6
- [semver](https://npm.io/package/semver.md) ^7.3.5
- [username](https://npm.io/package/username.md) ^5.1.0
- [read-pkg-up](https://npm.io/package/read-pkg-up.md) ^7.0.1

## Alternatives

- [raw-loader](https://npm.io/package/raw-loader.md) — 4.3M weekly downloads
- [plop](https://npm.io/package/plop.md) — 1.4M weekly downloads
- [webpack-deadcode-plugin](https://npm.io/package/webpack-deadcode-plugin.md) — 80.3K weekly downloads
- [@storybook/preact-vite](https://npm.io/package/@storybook/preact-vite.md) — 54.2K weekly downloads
- [vite-plugin-transform](https://npm.io/package/vite-plugin-transform.md) — 2.4K weekly downloads

## Recent versions

- 4.1.2 (latest) — 2021-07-10
- 4.1.1 — 2021-07-10
- 4.1.0 — 2021-04-08
- 4.0.0 — 2020-09-21
- 3.1.0 — 2020-09-21
- 3.0.0 — 2019-07-28
- 2.0.0 — 2019-01-03
- 1.0.0 — 2017-12-26
- 0.2.0 — 2017-02-08
- 0.1.0 — 2017-02-01

## README

# build-revision

[![Coverage Status](https://coveralls.io/repos/github/abhishekdev/build-revision/badge.svg)](https://coveralls.io/github/abhishekdev/build-revision)
[![Build status](https://ci.appveyor.com/api/projects/status/87rwahlhtj1903ag?svg=true)](https://ci.appveyor.com/project/abhishekdev/build-revision)
[![Build Status](https://travis-ci.org/abhishekdev/build-revision.svg)](https://travis-ci.org/abhishekdev/build-revision)

Generate semver compatible version to uniquely identify project build using [build metadata](http://semver.org/#spec-item-10)

## Usage

### Install

```sh
# OPTION: Use npm
$ npm install --save-dev build-revision

# OPTION: Use yarn
$ yarn add build-revision --dev
```

### Example

#### ES2015

```javascript
var buildRevision = require('build-revision');

buildRevision().then(function(version){
  console.log(version);
});
```

#### ES2017+

```javascript
import buildRevision from 'build-revision';

const fn = aync() => {
  const version = await buildRevision();
  console.log(version);
}
```

## Results

> If build metadata included in 'package.json' differs from that found by git. The SHA found by git is used.

### Working copy has no changes (_CI/CD Tools_)

Version                | Build Version
:--------------------- | :---------------------
0.1.0                  | 0.1.0+SHA.abcd123
0.1.0-pre              | 0.1.0-pre+SHA.abcd123
0.1.0-pre+SHA.01234567 | 0.1.0-pre+SHA.01234567

### Working copy has no changes (_Developer Machine_)

Version                | Build Version
:--------------------- | :--------------------------------------------------
0.1.0                  | 0.1.0+SHA.abcd123.currentuser.20170101T000000Z
0.1.0-pre              | 0.1.0-pre+SHA.abcd123.currentuser.20170101T000000Z
0.1.0-pre+SHA.01234567 | 0.1.0-pre+SHA.01234567.currentuser.20170101T000000Z

### Working copy is _NOT_ a git clone

Version   | Build Version
:-------- | :-------------------------------------------
0.1.0     | 0.1.0+NOREV.currentuser.20170101T000000Z
0.1.0-pre | 0.1.0-pre+NOREV.currentuser.20170101T000000Z

## API

### buildRevision(options)

- Appends `prefix.username.timestamp` to the version if repository does not exists
- Appends `prefix.githash.username.timestamp` to the version for a git repository with local changes
- Appends `prefix.githash` to the version for a git repository with no local changes

> The timestamp is an ISO 8601 UTC string

```yml
Type: Promise
Throws: Error
  - if the package version is not resolved
  - if the package version is not a valid semver
  - if the project is not a git repository
Returns:
  - semver compatible version with a build metadata part
```

### Options

#### options.prefix

Build metadata Prefix

```yml
Type: `String`
Default: `SHA`
```

#### options.cwd

Search for the closest package.json starting from this directory

```yml
Type: `String`
Default: `.`
```

## License [MIT](LICENSE)

---
_Source: https://npm.io/package/build-revision · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._