0
# Check Command
1

2
The check command validates that appropriate news fragments exist for changes in a branch, helping enforce changelog requirements in development workflows.
3

4
## Capabilities
5

6
### Check Main Function
7

8
The primary entry point for checking fragment requirements.
9

10
```python { .api }
11
def __main(
12
    comparewith: str | None,
13
    directory: str | None,
14
    config_path: str | None,
15
    staged: bool
16
) -> None:
17
    """
18
    Check for new fragments on a branch.
19
    
20
    Args:
21
        comparewith: Branch to compare against (None for auto-detection)
22
        directory: Directory to check in (None for current directory)
23
        config_path: Path to custom configuration file
24
        staged: Whether to include staged files in the comparison
25
        
26
    Exits:
27
        0: No fragments required or fragments found
28
        1: Fragments required but missing
29
    """
30
```
31

32
### CLI Entry Point
33

34
The Click-decorated command-line interface for the check command.
35

36
```python { .api }
37
def _main(
38
    compare_with: str | None,
39
    directory: str | None,
40
    config: str | None,
41
    staged: bool
42
) -> None:
43
    """
44
    Check for new fragments on a branch.
45
    
46
    Compares current branch against a base branch to determine if 
47
    news fragments are required for the changes made.
48
    """
49
```
50

51
## Branch Comparison Logic
52

53
### Default Branch Detection
54

55
The check command automatically detects the comparison branch using this priority:
56

57
1. Explicit `--compare-with` parameter
58
2. `origin/main` if it exists
59
3. `origin/master` if it exists  
60
4. `upstream/main` if it exists
61
5. `upstream/master` if it exists
62
6. First available remote branch
63

64
### File Change Analysis
65

66
The command analyzes changed files to determine if fragments are needed:
67

68
- Compares current branch against the base branch
69
- Optionally includes staged changes
70
- Excludes fragment files themselves from requiring fragments
71
- Uses VCS commands (git diff, hg diff) for file listing
72

73
## Usage Examples
74

75
### Basic Branch Check
76

77
```python
78
from towncrier.check import __main as check_main
79

80
# Check against default branch
81
check_main(
82
    comparewith=None,  # Auto-detect base branch
83
    directory=None,    # Current directory
84
    config_path=None,  # Auto-detect config
85
    staged=False       # Don't include staged files
86
)
87
```
88

89
### Custom Branch Comparison
90

91
```python
92
# Check against specific branch with staged files
93
check_main(
94
    comparewith="develop",
95
    directory="/path/to/project",
96
    config_path="custom-towncrier.toml",
97
    staged=True  # Include staged changes
98
)
99
```
100

101
### Command Line Usage
102

103
```bash
104
# Basic check against default branch
105
towncrier check
106

107
# Check against specific branch
108
towncrier check --compare-with develop
109

110
# Include staged files in check
111
towncrier check --staged
112

113
# Check in specific directory
114
towncrier check --dir /path/to/project --config custom.toml
115

116
# Check feature branch against main
117
towncrier check --compare-with origin/main
118
```
119

120
## VCS Integration
121

122
### Git Support
123

124
For Git repositories, the check command:
125

126
```python { .api }
127
# Git-specific functions from towncrier._git
128
def get_remote_branches(base_directory: str) -> list[str]:
129
    """Get list of remote branches."""
130

131
def list_changed_files_compared_to_branch(
132
    base_directory: str,
133
    branch: str, 
134
    staged: bool
135
) -> list[str]:
136
    """List files changed compared to branch."""
137

138
def get_default_compare_branch(branches: Container[str]) -> str | None:
139
    """Get default branch for comparison."""
140
```
141

142
### Mercurial Support
143

144
For Mercurial repositories:
145

146
```python { .api }
147
# Mercurial-specific functions from towncrier._hg  
148
def get_remote_branches(base_directory: str) -> list[str]:
149
    """Get list of remote branches."""
150

151
def list_changed_files_compared_to_branch(
152
    base_directory: str,
153
    branch: str,
154
    staged: bool  
155
) -> list[str]:
156
    """List files changed compared to branch."""
157

158
def get_default_compare_branch(branches: Container[str]) -> str | None:
159
    """Get default branch for comparison."""
160
```
161

162
### No VCS Support
163

164
For projects without version control:
165

166
```python { .api }
167
# No-VCS fallback functions from towncrier._novcs
168
def get_remote_branches(base_directory: str) -> list[str]:
169
    """Return empty list (no branches)."""
170

171
def list_changed_files_compared_to_branch(
172
    base_directory: str,
173
    branch: str,
174
    staged: bool
175
) -> list[str]:
176
    """Return empty list (no changes detectable)."""
177
```
178

179
## Fragment Detection
180

181
### Fragment File Recognition
182

183
The check command identifies fragment files using:
184

185
- Configured fragment directory locations
186
- Fragment type extensions from configuration
187
- Section-based fragment organization
188
- Ignore patterns from configuration
189

190
### Validation Logic
191

192
```python
193
# Pseudo-code for fragment validation
194
if no_files_changed:
195
    exit(0)  # No fragments required
196
    
197
changed_files = get_changed_files(branch, staged)
198
fragment_files = find_fragments(directory, config)
199

200
if has_required_changes(changed_files) and not fragment_files:
201
    exit(1)  # Fragments required but missing
202
else:
203
    exit(0)  # Requirements satisfied
204
```
205

206
## Configuration Options
207

208
The check command uses these configuration values:
209

210
- `directory`: Fragment directory location
211
- `package_dir`: Package directory for fragment resolution
212
- `package`: Package name for fragment location
213
- `types`: Fragment type definitions for recognition
214
- `sections`: Section configuration for multi-section projects
215
- `ignore`: Patterns for files that don't require fragments
216

217
## Error Handling
218

219
The check command handles these scenarios:
220

221
- **CalledProcessError**: VCS command failures (git/hg errors)
222
- **ConfigError**: Invalid or missing configuration
223
- **Branch detection failure**: No suitable comparison branch found
224
- **Permission errors**: Cannot access repository or files
225
- **Network errors**: Cannot fetch remote branch information
226

227
## CI Integration
228

229
Common usage patterns in continuous integration:
230

231
```bash
232
# In GitHub Actions, GitLab CI, etc.
233
towncrier check --compare-with ${{ github.event.pull_request.base.ref }}
234

235
# In pre-commit hooks
236
towncrier check --staged
237

238
# For feature branch workflows
239
towncrier check --compare-with origin/develop
240
```