Skip to content

Consolidate command-line argument tables into single unified reference and add --result alias #72

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Malcolmnixon merged 2 commits into from
Apr 13, 2026
Merged

Consolidate command-line argument tables into single unified reference and add --result alias #72

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6630495
Consolidate command-line argument tables into unified table in README…
Copilot Apr 13, 2026
b5d6f4f
Add --result as legacy alias for --results argument
Copilot Apr 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 27 additions & 67 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,75 +74,35 @@ This consolidates versions from all jobs and generates a markdown report.

## Command-Line Options

### Global Options

| Option | Description |
| -------------------- | ------------------------------------------------------------ |
| `-v`, `--version` | Display version information |
| `-?`, `-h`, `--help` | Display help message |
| `--silent` | Suppress console output |
| `--log <file>` | Write output to log file |

### Lint Mode

Validate a `.versionmark.yaml` configuration file for issues:

```bash
versionmark --lint [<config-file>]
```

| Option | Description |
| ----------------------- | --------------------------------------------------------------------- |
| `--lint [<config-file>]`| Check configuration file (default: `.versionmark.yaml`) |

Lint reports all issues with filename and line/column location. Exits with code 0 if no
issues are found, or 1 if any issues are detected.

**Example:**

```bash
# Lint the default config file
versionmark --lint

# Lint a specific config file
versionmark --lint path/to/.versionmark.yaml
```

### Capture Mode

Capture tool versions from the current environment:

```bash
versionmark --capture --job-id <job-identifier> [options] [-- tool1 tool2 ...]
```

| Option | Description |
| ------------------------- | ------------------------------------------------------------ |
| `--capture` | Enable capture mode |
| `--job-id <id>` | **(Required)** Unique identifier for this CI/CD job |
| `--output <file>` | Output JSON file (default: `versionmark-<job-id>.json`) |
| `-- <tools...>` | List of tool names to capture (default: all tools in config) |

**Example:** Capture specific tools only:

```bash
versionmark --capture --job-id "windows-build" -- dotnet node npm
```

### Publish Mode

Publish captured versions to markdown documentation:

```bash
versionmark --publish --report <file> [options] [-- pattern1 pattern2 ...]
```text
Usage: versionmark [options]
versionmark --lint [<config-file>]
versionmark --capture --job-id <id> [options] [-- tool1 tool2 ...]
versionmark --publish --report <file> [options] [-- pattern1 pattern2 ...]
```

| Option | Description |
| ------------------------- | ------------------------------------------------------------ |
| `--publish` | Enable publish mode |
| `--report <file>` | **(Required)** Output markdown file path |
| `--report-depth <depth>` | Heading depth for markdown output (default: 2) |
| `-- <patterns...>` | Glob patterns for JSON files (default: `versionmark-*.json`) |
| Option | Description |
| ------------------------- | ---------------------------------------------------------------- |
| **General** | |
| `-v`, `--version` | Display version information |
| `-?`, `-h`, `--help` | Display help message |
| `--silent` | Suppress console output |
| `--log <file>` | Write output to log file |
| **Lint Mode** | |
| `--lint [<config-file>]` | Check configuration file (default: `.versionmark.yaml`) |
| **Capture Mode** | |
| `--capture` | Enable capture mode |
| `--job-id <id>` | **(Required)** Unique identifier for this CI/CD job |
| `--output <file>` | Output JSON file (default: `versionmark-<job-id>.json`) |
| `-- <tools...>` | List of tool names to capture (default: all tools in config) |
| **Publish Mode** | |
| `--publish` | Enable publish mode |
| `--report <file>` | **(Required)** Output markdown file path |
| `--report-depth <depth>` | Heading depth for markdown output (default: 2, min: 1, max: 6) |
Comment thread
Malcolmnixon marked this conversation as resolved.
| `-- <patterns...>` | Glob patterns for JSON files (default: `versionmark-*.json`) |
| **Self-Validation** | |
| `--validate` | Run self-validation tests |
| `--results <file>` | Write validation results to file (`.trx` or `.xml`) |

## Configuration File

Expand Down
70 changes: 29 additions & 41 deletions docs/user_guide/guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,31 +86,39 @@ This generates a markdown file consolidating versions from all jobs.

# Command-Line Reference

## Global Options

These options are available for all commands:

| Option | Description |
| -------------------- | ------------------------------------------------------------ |
| `-v`, `--version` | Display version information |
| `-?`, `-h`, `--help` | Display help message |
| `--silent` | Suppress console output |
| `--log <file>` | Write output to log file |

## Lint Command
## Options

| Option | Description |
| ------------------------- | ---------------------------------------------------------------- |
| **General** | |
| `-v`, `--version` | Display version information |
| `-?`, `-h`, `--help` | Display help message |
| `--silent` | Suppress console output |
| `--log <file>` | Write output to log file |
| **Lint Mode** | |
| `--lint [<config-file>]` | Check configuration file (default: `.versionmark.yaml`) |
| **Capture Mode** | |
| `--capture` | Enable capture mode |
| `--job-id <id>` | **(Required)** Unique identifier for this CI/CD job |
| `--output <file>` | Output JSON file (default: `versionmark-<job-id>.json`) |
| `-- <tools...>` | List of tool names to capture (default: all tools in config) |
| **Publish Mode** | |
| `--publish` | Enable publish mode |
| `--report <file>` | **(Required)** Output markdown file path |
| `--report-depth <depth>` | Heading depth for markdown output (default: 2, min: 1, max: 6) |
Comment thread
Malcolmnixon marked this conversation as resolved.
| `-- <patterns...>` | Glob patterns for JSON files (default: `versionmark-*.json`) |
| **Self-Validation** | |
| `--validate` | Run self-validation tests |
| `--results <file>` | Write validation results to file (`.trx` or `.xml`) |

## Lint Mode

Validate a `.versionmark.yaml` configuration file for issues:

```bash
versionmark --lint [<config-file>]
```

### Lint Options

| Option | Description |
| ------------------------ | ---------------------------------------------------------------- |
| `--lint [<config-file>]` | Check configuration file (default: `.versionmark.yaml`) |

### Lint Behavior

The lint command:
Expand Down Expand Up @@ -157,26 +165,15 @@ For example:
.versionmark.yaml(8,5): error: Tool 'node' 'regex' contains an invalid regex: ...
```

## Capture Command
## Capture Mode

Capture tool versions from the current environment:

```bash
versionmark --capture --job-id <job-identifier> [options] [-- tool1 tool2 ...]
```

### Options

| Option | Description |
| ------------------------- | ----------------------------------------------------------------------------------- |
| `--capture` | Enable capture mode |
| `--job-id <id>` | **(Required)** Unique identifier for this CI/CD job. This is used to differentiate |
| | versions captured in different environments or configurations. |
| `--output <file>` | Path to output JSON file (default: `versionmark-<job-id>.json`) |
| `-- <tools...>` | List of tool names to capture. If not specified, all tools defined in the |
| | configuration file will be captured. |

### Example
### Examples

```bash
# Capture all tools defined in config
Expand All @@ -189,23 +186,14 @@ versionmark --capture --job-id "linux-gcc" -- gcc make cmake
versionmark --capture --job-id "macos" --output versions/macos.json
```

## Publish Command
## Publish Mode

Publish captured versions to markdown documentation:

```bash
versionmark --publish --report <file> [options] [-- pattern1 pattern2 ...]
```

### Publish Options

| Option | Description |
| ------------------------ | ---------------------------------------------------------------- |
| `--publish` | Enable publish mode |
| `--report <file>` | **(Required)** Path to output markdown file |
| `--report-depth <depth>` | Heading depth for markdown output (default: 2, min: 1, max: 6) |
| `-- <patterns...>` | Glob patterns for JSON files (default: `versionmark-*.json`) |

### Publish Examples

```bash
Expand Down
1 change: 1 addition & 0 deletions src/DemaConsulting.VersionMark/Cli/Context.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -345,6 +345,7 @@ private int ParseArgument(string arg, string[] args, int index)
LogFile = GetRequiredStringArgument(arg, args, index, "a filename argument");
return index + 1;

case "--result":
case "--results":
ResultsFile = GetRequiredStringArgument(arg, args, index, "a results filename argument");
return index + 1;
Expand Down
14 changes: 14 additions & 0 deletions test/DemaConsulting.VersionMark.Tests/Cli/ContextTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,20 @@ public void Context_Create_ResultsFlag_SetsResultsFile()
Assert.AreEqual(0, context.ExitCode);
}

/// <summary>
/// Test creating a context with the legacy result flag (alias for --results).
/// </summary>
[TestMethod]
public void Context_Create_ResultFlag_SetsResultsFile()
{
// Arrange & Act - Create context with --result flag (legacy alias)
using var context = Context.Create(["--result", "test.trx"]);

// Assert - Verify results file is set
Assert.AreEqual("test.trx", context.ResultsFile);
Assert.AreEqual(0, context.ExitCode);
}

/// <summary>
/// Test creating a context with the log flag.
/// </summary>
Expand Down
Loading