0
# Build Command
1

2
The build command combines individual news fragments into a comprehensive changelog entry. It supports both command-line and programmatic usage with extensive customization options.
3

4
## Capabilities
5

6
### Build Main Function
7

8
The primary entry point for building changelogs from news fragments.
9

10
```python { .api }
11
def __main(
12
    draft: bool,
13
    directory: str | None,
14
    config_file: str | None,
15
    project_name: str | None,
16
    project_version: str | None,
17
    project_date: str | None,
18
    answer_yes: bool,
19
    answer_keep: bool
20
) -> None:
21
    """
22
    Build a combined news file from news fragments.
23
    
24
    Args:
25
        draft: If True, render to stdout without writing files or checking versions
26
        directory: Directory to build in (None for current directory)
27
        config_file: Path to custom configuration file (None for auto-detection)
28
        project_name: Custom project name (None to use config or auto-detect)
29
        project_version: Custom version string (None to use config or auto-detect) 
30
        project_date: Custom date string (None for current date)
31
        answer_yes: If True, automatically confirm fragment removal
32
        answer_keep: If True, keep fragments instead of removing them
33
    """
34
```
35

36
### CLI Entry Point
37

38
The Click-decorated command-line interface for the build command.
39

40
```python { .api }
41
def _main(
42
    draft: bool,
43
    directory: str | None,
44
    config_file: str | None,
45
    project_name: str | None,
46
    project_version: str | None,
47
    project_date: str | None,
48
    answer_yes: bool,
49
    answer_keep: bool
50
) -> None:
51
    """
52
    Build a combined news file from news fragment.
53
    
54
    This is the Click command entry point that wraps __main with error handling.
55
    """
56
```
57

58
### Utility Functions
59

60
Helper functions for date handling and validation.
61

62
```python { .api }
63
def _get_date() -> str:
64
    """Get current date in ISO format (YYYY-MM-DD)."""
65

66
def _validate_answer(ctx: Context, param: Option, value: bool) -> bool:
67
    """
68
    Validate that --yes and --keep options are not used together.
69
    
70
    Args:
71
        ctx: Click context
72
        param: Click option parameter
73
        value: Option value
74
        
75
    Returns:
76
        bool: The validated value
77
        
78
    Raises:
79
        click.Abort: If both --yes and --keep are specified
80
    """
81

82
def should_remove_fragment_files(
83
    fragment_filenames: list[str],
84
    answer_yes: bool,
85
    answer_keep: bool
86
) -> bool:
87
    """
88
    Determine if fragment files should be removed based on user options.
89
    
90
    Args:
91
        fragment_filenames: List of fragment file paths to potentially remove
92
        answer_yes: Whether user confirmed removal
93
        answer_keep: Whether user wants to keep fragments
94
        
95
    Returns:
96
        bool: True if fragments should be removed
97
    """
98
```
99

100
## Usage Examples
101

102
### Basic Build
103

104
```python
105
from towncrier.build import __main as build_main
106

107
# Build with defaults - removes fragments after build
108
build_main(
109
    draft=False,
110
    directory=None,
111
    config_file=None,  
112
    project_name=None,
113
    project_version=None,
114
    project_date=None,
115
    answer_yes=True,
116
    answer_keep=False
117
)
118
```
119

120
### Draft Build
121

122
```python
123
# Generate draft output to stdout without modifying files
124
build_main(
125
    draft=True,  # Output to stdout only
126
    directory=None,
127
    config_file=None,
128
    project_name="My Project",
129
    project_version="1.2.0", 
130
    project_date="2024-01-15",
131
    answer_yes=False,  # Not relevant for draft
132
    answer_keep=False  # Not relevant for draft
133
)
134
```
135

136
### Build with Custom Configuration
137

138
```python
139
# Build using custom config and keeping fragments
140
build_main(
141
    draft=False,
142
    directory="/path/to/project",
143
    config_file="/path/to/custom-towncrier.toml",
144
    project_name="Custom Project Name",
145
    project_version="2.0.0-beta",
146
    project_date="2024-12-25",
147
    answer_yes=False,  # Will prompt user
148
    answer_keep=True   # Keep fragments after build
149
)
150
```
151

152
### Command Line Usage
153

154
```bash
155
# Basic build
156
towncrier build
157

158
# Draft build to preview output  
159
towncrier build --draft
160

161
# Build with custom version and date
162
towncrier build --version 1.5.0 --date 2024-01-01
163

164
# Build and keep fragments
165
towncrier build --keep
166

167
# Build with auto-confirmation
168
towncrier build --yes
169

170
# Build in specific directory with custom config
171
towncrier build --dir /path/to/project --config custom.toml
172
```
173

174
## Configuration Options
175

176
The build command uses these configuration values:
177

178
- `template`: Jinja2 template for rendering the changelog
179
- `start_string`: Marker in the news file where new content is inserted
180
- `filename`: Name of the news/changelog file
181
- `package`: Package name for version detection
182
- `package_dir`: Directory containing the package
183
- `version`: Static version string
184
- `name`: Project name for the changelog
185
- `title_format`: Format string for section titles
186
- `issue_format`: Format string for issue references
187

188
## Error Handling
189

190
The build command handles these error scenarios:
191

192
- **ConfigError**: Invalid or missing configuration
193
- **UsageError**: Missing required options like version
194
- **ClickException**: General CLI errors
195
- **Template errors**: Invalid Jinja2 templates
196
- **File access errors**: Permission or path issues
197
- **VCS errors**: Git/Mercurial command failures