0
# Version Management
1

2
Automated versioning of packages with conventional commits, git tagging, and changelog generation.
3

4
## Capabilities
5

6
### Version Command
7

8
Updates package versions, creates git tags, and generates changelogs.
9

10
```bash { .api }
11
# Interactive version selection
12
lerna version
13

14
# Explicit version increment
15
lerna version patch
16
lerna version minor  
17
lerna version major
18
lerna version premajor
19
lerna version preminor
20
lerna version prepatch
21
lerna version prerelease
22

23
# Explicit version number
24
lerna version 1.2.3
25

26
# Graduate prerelease versions to stable
27
lerna version --conventional-graduate
28

29
# Create prerelease versions
30
lerna version --conventional-prerelease
31

32
# Use conventional commits for automatic version determination
33
lerna version --conventional-commits
34

35
# Create GitHub/GitLab release
36
lerna version --create-release github
37
lerna version --create-release gitlab
38

39
# Custom commit message
40
lerna version --message "chore: release %s"
41

42
# Skip git operations
43
lerna version --no-git-tag-version
44
lerna version --no-push
45

46
# Allow versioning on specific branch(es)
47
lerna version --allow-branch main
48
lerna version --allow-branch "release/*"
49

50
# Force publish all packages (ignore change detection)
51
lerna version --force-publish
52

53
# Include dependencies in version updates
54
lerna version --exact
55
```
56

57
### Advanced Version Options
58

59
Additional options for fine-tuning version behavior:
60

61
```bash { .api }
62
# Conventional commits options
63
lerna version --conventional-commits
64
lerna version --conventional-bump-prerelease
65
lerna version --changelog-preset angular
66
lerna version --changelog-entry-additional-markdown "Additional notes"
67
lerna version --force-conventional-graduate
68

69
# Git and commit options  
70
lerna version --signoff-git-commit
71
lerna version --force-git-tag
72
lerna version --tag-version-separator "@"
73
lerna version --git-tag-command "custom-tag-command"
74
lerna version --no-granular-pathspec
75
lerna version --no-commit-hooks
76

77
# Package and dependency management
78
lerna version --sync-dist-version
79
lerna version --run-scripts-on-lockfile-update
80
lerna version --npm-client-args "--no-package-lock"
81
lerna version --premajor-version-bump force-patch
82

83
# Change detection and filtering
84
lerna version --ignore-changes "**/*.md" "**/__tests__/**"
85
lerna version --include-merged-tags
86
lerna version --no-private
87

88
# Output and automation
89
lerna version --json
90
lerna version --yes
91
lerna version --ignore-scripts
92
```
93

94
**Advanced Option Details:**
95

96
- `--conventional-bump-prerelease` - Bump prerelease versions when conventional commits require it
97
- `--changelog-preset` - Specify custom conventional-changelog preset (default: angular)  
98
- `--changelog-entry-additional-markdown` - Add custom markdown to changelog entries
99
- `--force-conventional-graduate` - Force graduation regardless of changes
100
- `--signoff-git-commit` - Add Signed-off-by line to commit messages
101
- `--force-git-tag` - Force creation of git tags even if they exist
102
- `--tag-version-separator` - Customize separator for independent versioning tags
103
- `--git-tag-command` - Use custom command for git tag creation
104
- `--no-granular-pathspec` - Stage all changes globally instead of file-by-file
105
- `--no-commit-hooks` - Skip git commit hooks during version commit
106
- `--sync-dist-version` - Update package.json in distribution directories
107
- `--run-scripts-on-lockfile-update` - Run lifecycle scripts during lockfile updates
108
- `--npm-client-args` - Pass additional arguments to npm client
109
- `--premajor-version-bump` - Control pre-major version bump behavior (default, force-patch)
110
- `--ignore-changes` - Ignore specific file patterns for change detection
111
- `--include-merged-tags` - Include tags from merged branches in change detection
112
- `--no-private` - Exclude private packages from versioning
113
- `--json` - Output version information in JSON format
114
- `--ignore-scripts` - Disable all lifecycle scripts during versioning
115

116
### Version Workflow
117

118
The `lerna version` command performs the following steps:
119

120
1. **Change Detection**: Identifies packages that have changed since the last release
121
2. **Version Selection**: Prompts for version increments or uses conventional commits
122
3. **Cross-dependencies**: Updates references between workspace packages
123
4. **Git Operations**: Creates commits and tags for the new versions
124
5. **Release Creation**: Optionally creates GitHub/GitLab releases
125

126
### Conventional Commits
127

128
Lerna supports conventional commits for automatic version determination:
129

130
```bash { .api }
131
# Enable conventional commits
132
lerna version --conventional-commits
133

134
# Graduate prereleases using conventional commits
135
lerna version --conventional-graduate
136

137
# Create prereleases using conventional commits  
138
lerna version --conventional-prerelease
139

140
# Combine with release creation
141
lerna version --conventional-commits --create-release github
142
```
143

144
**Conventional Commit Format:**
145
```
146
<type>[optional scope]: <description>
147

148
[optional body]
149

150
[optional footer(s)]
151
```
152

153
**Version Impact:**
154
- `fix:` → patch version
155
- `feat:` → minor version  
156
- `BREAKING CHANGE:` or `!` → major version
157

158
## Version Configuration
159

160
```typescript { .api }
161
interface VersionConfig {
162
  /** Branches allowed for versioning */
163
  allowBranch?: string | string[];
164
  /** Use conventional commits for version determination */
165
  conventionalCommits?: boolean;
166
  /** Commit message template (%s = version, %v = tag) */
167
  message?: string;
168
  /** Push commits and tags to remote */
169
  push?: boolean;
170
  /** Create release on GitHub/GitLab */
171
  createRelease?: 'github' | 'gitlab';
172
  /** Sign git commits and tags */
173
  signGitCommit?: boolean;
174
  /** Sign git tags */
175
  signGitTag?: boolean;
176
  /** Force publish all packages */
177
  forcePublish?: boolean | string | string[];
178
  /** Use exact versions for cross-dependencies */
179
  exact?: boolean;
180
  /** Preid for prerelease versions */
181
  preid?: string;
182
  /** Include dependencies in version updates */  
183
  includeDependencies?: boolean;
184
  /** Include dependents in version updates */
185
  includeDependents?: boolean;
186
  /** Graduate prerelease packages to stable */
187
  conventionalGraduate?: boolean | string | string[];
188
  /** Create prerelease versions */
189
  conventionalPrerelease?: boolean | string | string[];
190
}
191
```
192

193
**Usage in lerna.json:**
194

195
```json
196
{
197
  "version": "independent",
198
  "command": {
199
    "version": {
200
      "allowBranch": ["main", "release/*"],
201
      "conventionalCommits": true,
202
      "message": "chore: release %s",
203
      "createRelease": "github",
204
      "push": true,
205
      "exact": true
206
    }
207
  }
208
}
209
```
210

211
## Versioning Modes
212

213
### Fixed Mode
214

215
All packages share the same version number.
216

217
```json
218
{
219
  "version": "1.2.3"
220
}
221
```
222

223
### Independent Mode
224

225
Each package maintains its own version.
226

227
```json
228
{
229
  "version": "independent"
230
}
231
```
232

233
## Git Integration
234

235
```bash { .api }
236
# Skip git tag creation
237
lerna version --no-git-tag-version
238

239
# Skip pushing to remote
240
lerna version --no-push
241

242
# Custom tag prefix
243
lerna version --tag-version-prefix="v"
244

245
# Sign commits and tags
246
lerna version --sign-git-commit --sign-git-tag
247

248
# Allow versioning on dirty working tree
249
lerna version --allow-dirty
250
```
251

252
## Release Creation
253

254
```bash { .api }
255
# Create GitHub release with generated changelog
256
lerna version --create-release github
257

258
# Create GitLab release
259
lerna version --create-release gitlab
260

261
# Skip release creation
262
lerna version --no-create-release
263
```
264

265
Release creation requires:
266
- **GitHub**: `GH_TOKEN` or `GITHUB_TOKEN` environment variable
267
- **GitLab**: `GL_TOKEN` or `GITLAB_TOKEN` environment variable
268

269
The release will include:
270
- Auto-generated changelog from conventional commits
271
- Links to commits and pull requests
272
- Package-specific release notes (in independent mode)