Draft release

CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
+
+## [4.1.0](https://github.com/tvdstaaij/node-git-describe/compare/v4.0.4...v4.1.0) (2021-08-16)
+
+
+### Features
+
+* Add `long` option to match behaviour of git describe --long (Fixes [#15](https://github.com/tvdstaaij/node-git-describe/issues/15)) ([0469061](https://github.com/tvdstaaij/node-git-describe/commit/046906171c9db8585577bdc1cd827edd69363ca7))
+* Add typescript types ([9638b74](https://github.com/tvdstaaij/node-git-describe/commit/9638b7447a9e346f7e8ac678d8bbe2770ea65abd))
+
+
+### Fixes and Improvements
+
+* Throw the correct error message when gitDescribeSync is invoked without git in the $PATH (Fixes [#17](https://github.com/tvdstaaij/node-git-describe/issues/17)) ([2d1df12](https://github.com/tvdstaaij/node-git-describe/commit/2d1df12e15751ba079dd3a4b623ecbe10df0db91))

CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing
+
+Contributions are welcome!
+
+Release notes and the version number for the next
+release are generated from the commit history.
+Here are some guidelines on formatting your commits to make sure that the
+release notes will be correct after your change is accepted.
+
+Ignoring these guidelines is fine, but it means that your change may be squash-merged so that the changelog contains the right contents.
+
+Release notes and version bumping are managed by `standard-version`. This uses the
+[Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) specification to decide what will appear in the changelog.
+
+## Commits
+
+In general the format is `<type>(<scope>): <message>`. The `scope` and the `message` can be anything.
+The `type` can also be anything, but if it is `fix` or `feat` then it will appear in the release notes:
+
+- `feat(options):` or `feat:` messages appear under "New Features", and trigger minor version bumps.
+- `fix(some other scope):` or `fix:` messages appear under "Fixes and improvements", and trigger patch version bumps.
+
+These communicate changes that users may want to know about. Not all changes that could be considered "fixes"
+are changes that users would want to see in the changelog.
+If you have a fix that shouldn't be in the changelog, some example types include `docs`, `chore`, `test`, `refactor`, `build` etc.
+
+If your commit message introduces a breaking change, please indicate that it is a breaking change with `!`
+after the type and scope. For example, the following commit message indicates a breaking change:
+
+```
+fix(something)!: The signature for the something method has changed
+```
+
+You can also include a footer in the commit that
+starts with the text `BREAKING CHANGE:`. This is useful if you need to provide
+more context. Markdown formatting is available in the footer section.
+
+Breaking changes trigger major version bumps and always appear in the release notes, even if they are not `feat` or `fix`.
+
+For more information, please see the
+[Conventional Commit Specification](https://www.conventionalcommits.org/en/v1.0.0/)
+
+## Cutting a release
+
+To modify the changelog, bump the version, and create the appropriate git tag, run:
+
+```
+npm run release
+```
+
+If you just want to confirm what the release notes and version will be, you can do a dry run with:
+
+```
+npm run release -- --dry-run
+```
+
+If you need to do a prerelease version (say with a suffix of `-alpha`), you can do:
+
+```
+npm run release -- --prerelease alpha
+```
+
+For more information see the [standard-version documentation](https://github.com/conventional-changelog/standard-version#readme)

README.md

@@ -93,7 +93,8 @@ Option             | Default     | Description
 ------------------ | ----------- | -----------
 `dirtyMark`        | `'-dirty'`  | Dirty mark to use if repo state is dirty (see git describe's `--dirty`).
 `dirtySemver`      | `true`      | Appends the dirty mark to `semverString` if repo state is dirty.
-`longSemver`       | `false`     | Always adds commit distance and hash to `semverString` (similar to git describe's `--long`).
+`long`             | `true`      | Always adds commit distance and hash to `raw`, `suffix` and `.toString()` (matches the behaviour of git describe's `--long`)
+`longSemver`       | `false`     | Always adds commit distance and hash to `semverString` (similar to git describe's `--long`, but for semver).
 `requireAnnotated` | `false`     | Uses `--tags` if false, so that simple git tags are allowed.
 `match`            | `'v[0-9]*'` | Uses `--match` to filter tag names. By default only tags resembling a version number are considered.
 `customArguments`  | `[]`        | Array of additional arguments to pass to `git describe`. Not all arguments are useful and some may even break the library, but things like `--abbrev` and `--candidates` should be safe to add.

index.d.ts

@@ -0,0 +1,56 @@
+import { SemVer } from "semver";
+
+export type GitInfo = {
+  dirty: boolean;
+  raw: string;
+  hash: string;
+  distance: null | number;
+  tag: null | string;
+  semver: null | SemVer;
+  suffix: string;
+  semverString: null | string;
+  toString: () => string;
+};
+export type GitDescribeOptions = {
+  dirtyMark?: string;
+  dirtySemver?: boolean;
+  long?: boolean;
+  longSemver?: boolean;
+  requireAnnotated?: boolean;
+  match?: string;
+  customArguments?: Array<string>;
+};
+
+export type Callback = (err: Error, gitInfo: GitInfo) => void;
+
+export declare function gitDescribe(directory: string): Promise<GitInfo>;
+export declare function gitDescribe(
+  options: GitDescribeOptions
+): Promise<GitInfo>;
+export declare function gitDescribe(
+  directory: string,
+  options: GitDescribeOptions
+): Promise<GitInfo>;
+
+export declare function gitDescribe(callback: Callback): void;
+export declare function gitDescribe(
+  options: GitDescribeOptions,
+  callback: Callback
+): void;
+export declare function gitDescribe(
+  directory: string,
+  callback: Callback
+): void;
+export declare function gitDescribe(
+  directory: string,
+  options: GitDescribeOptions,
+  callback: Callback
+): void;
+
+export declare function gitDescribeSync(): GitInfo;
+export declare function gitDescribeSync(directory: string): GitInfo;
+export declare function gitDescribeSync(options: GitDescribeOptions): GitInfo;
+export declare function gitDescribeSync(
+  directory: string,
+  options: GitDescribeOptions
+): GitInfo;

lib/git-describe.js

@@ -24,6 +24,7 @@ module.exports = function gitDescribe(directory, options, cb) {
     options = _.defaults({}, options, {
         dirtySemver: true,
         longSemver: false,
+        long: true,
         requireAnnotated: false,
         match: 'v[0-9]*',
         customArguments: []
@@ -43,7 +44,7 @@ module.exports = function gitDescribe(directory, options, cb) {
         execFunc(_.partialRight(resultHandler, cb));
     } else {
         var result = execFunc();
-        return resultHandler(result, result.stdout, result.stderr, null);
+        return resultHandler(result.error, result.stdout, result.stderr, null);
     }
 };
 
@@ -66,8 +67,8 @@ function createExecArgs(directory, options) {
 function handleProcessResult(result, stdout, stderr, cb, parser) {
     if (result && result.status !== 0) {
         var code = result.status || result.code;
-        var errMsg = 'Git returned with status ' + code + ': ' +
-            stderr.toString().trim();
+        var errMsg = 'Git returned with status ' + code +
+            (stderr ? ': ' + stderr.toString().trim() : '');
         switch (code) {
         case 'ENOENT':
             errMsg = 'Git executable not found in PATH (' + process.env.PATH + ')';
@@ -126,7 +127,12 @@ function parseDescription(description, options) {
                 output.semverString += '+' + build;
         }
     }
-    output.suffix = suffixTokens.join('-');
+    if (!options.long && output.tag && output.distance === 0) {
+        output.suffix = '';
+        output.raw = output.tag;
+    } else {
+        output.suffix = suffixTokens.join('-');
+    }
     if (output.dirty) output.suffix += options.dirtyMark;
     output.toString = function() { return output.raw; };
     return output;