0
# File Exclusion & CI Integration
1
2
Utilities for excluding files from processing and handling CI/CD environment considerations for proper git history access. These functions help optimize plugin performance and ensure reliable operation in continuous integration environments.
3
4
## Capabilities
5
6
### File Exclusion
7
8
Pattern-based file exclusion system supporting glob patterns to exclude specific files or directories from git revision date processing.
9
10
```python { .api }
11
def exclude(src_path: str, globs: List[str]) -> bool:
12
"""
13
Determine if a file path should be excluded from processing.
14
15
Parameters:
16
- src_path (str): Relative source path of the file
17
- globs (List[str]): List of glob patterns to match against
18
19
Returns:
20
bool: True if file should be excluded, False otherwise
21
"""
22
```
23
24
**Usage:**
25
26
```python
27
from mkdocs_git_revision_date_localized_plugin.exclude import exclude
28
29
# Define exclusion patterns
30
exclusion_patterns = [
31
"drafts/*",
32
"*.tmp",
33
"temp/**/*",
34
"generated/*.md"
35
]
36
37
# Check if file should be excluded
38
file_path = "docs/drafts/my-draft.md"
39
should_exclude = exclude(file_path, exclusion_patterns) # Returns True
40
41
file_path = "docs/index.md"
42
should_exclude = exclude(file_path, exclusion_patterns) # Returns False
43
```
44
45
**Supported Patterns:**
46
47
```python
48
# Examples of supported glob patterns
49
patterns = [
50
"*.tmp", # All .tmp files
51
"drafts/*", # All files in drafts directory
52
"temp/**/*", # All files in temp directory recursively
53
"*/private.md", # private.md in any directory
54
"docs/old/*.md", # All .md files in docs/old/
55
]
56
```
57
58
**Configuration Integration:**
59
60
```yaml
61
plugins:
62
- git-revision-date-localized:
63
exclude:
64
- "drafts/*"
65
- "*.tmp"
66
- "generated/**/*"
67
- "private/*.md"
68
```
69
70
### CI/CD Environment Detection
71
72
Functions for detecting and handling continuous integration environments that may have limited git history due to shallow clones.
73
74
```python { .api }
75
def raise_ci_warnings(repo) -> None:
76
"""
77
Raise warnings for CI environments with shallow git clones.
78
79
Parameters:
80
- repo: GitPython repository object
81
"""
82
83
def is_shallow_clone(repo) -> bool:
84
"""
85
Determine if repository is a shallow clone.
86
87
Parameters:
88
- repo: GitPython repository object
89
90
Returns:
91
bool: True if repository is shallow, False otherwise
92
"""
93
94
def commit_count(repo) -> int:
95
"""
96
Count the number of commits in repository.
97
98
Parameters:
99
- repo: GitPython repository object
100
101
Returns:
102
int: Number of commits in repository
103
"""
104
```
105
106
**Usage:**
107
108
```python
109
from mkdocs_git_revision_date_localized_plugin.ci import raise_ci_warnings, is_shallow_clone, commit_count
110
from git import Repo
111
112
# Initialize repository
113
repo = Repo("/path/to/repo")
114
115
# Check if shallow clone
116
if is_shallow_clone(repo):
117
print("Repository is a shallow clone")
118
119
# Count commits
120
num_commits = commit_count(repo)
121
print(f"Repository has {num_commits} commits")
122
123
# Raise appropriate warnings for CI environment
124
raise_ci_warnings(repo)
125
```
126
127
### CI Environment Detection
128
129
The plugin automatically detects and provides specific guidance for common CI/CD platforms:
130
131
**GitHub Actions:**
132
133
```python { .api }
134
# Detects: GITHUB_ACTIONS environment variable
135
# Warning triggered when: commit_count == 1 (default fetch-depth: 1)
136
# Recommendation: Set fetch-depth: 0 in checkout action
137
```
138
139
**GitLab CI:**
140
141
```python { .api }
142
# Detects: GITLAB_CI environment variable
143
# Warning triggered when: commit_count < 50 (default GIT_DEPTH: 50)
144
# Recommendation: Set GIT_DEPTH: 0 in .gitlab-ci.yml
145
```
146
147
**Bitbucket Pipelines:**
148
149
```python { .api }
150
# Detects: BITBUCKET_BUILD_NUMBER environment variable
151
# Warning triggered when: commit_count < 50 (default depth: 50)
152
# Recommendation: Set clone depth to full
153
```
154
155
**Azure DevOps:**
156
157
```python { .api }
158
# Detects: Agent.Source.Git.ShallowFetchDepth environment variable
159
# Warning triggered when: configured depth < actual commits
160
# Recommendation: Remove shallow fetch settings
161
```
162
163
### CI Configuration Examples
164
165
**GitHub Actions:**
166
167
```yaml
168
- uses: actions/checkout@v4
169
with:
170
fetch-depth: 0 # Fetch full history
171
```
172
173
**GitLab CI:**
174
175
```yaml
176
variables:
177
GIT_DEPTH: 0 # Fetch full history
178
179
job:
180
script:
181
- mkdocs build
182
```
183
184
**Bitbucket Pipelines:**
185
186
```yaml
187
pipelines:
188
default:
189
- step:
190
name: Build docs
191
clone:
192
depth: full # Fetch full history
193
script:
194
- mkdocs build
195
```
196
197
**Azure DevOps:**
198
199
```yaml
200
- checkout: self
201
fetchDepth: 0 # Fetch full history
202
```
203
204
### Error Handling Integration
205
206
The utilities integrate with the plugin's error handling system through configuration options.
207
208
```python { .api }
209
# Configuration options affecting utility behavior
210
config = {
211
"fallback_to_build_date": True, # Use build date when git fails
212
"strict": False, # Don't treat warnings as errors
213
"enable_parallel_processing": True # Use multiprocessing for performance
214
}
215
```
216
217
**Error Recovery:**
218
219
```python
220
# When git operations fail, utilities can fall back to:
221
# 1. Current build timestamp
222
# 2. File modification time
223
# 3. Default epoch time
224
225
# Controlled by fallback_to_build_date configuration
226
```
227
228
### Cross-Platform Compatibility
229
230
File exclusion handles cross-platform path differences automatically.
231
232
```python { .api }
233
# Handles both Unix and Windows path separators
234
# Unix: "docs/drafts/file.md"
235
# Windows: "docs\\drafts\\file.md"
236
237
# Both patterns work on all platforms:
238
exclude_patterns = [
239
"docs/drafts/*", # Unix-style (works everywhere)
240
"docs\\drafts\\*", # Windows-style (converted automatically)
241
]
242
```
243
244
### Performance Considerations
245
246
**File Exclusion Optimization:**
247
248
```python
249
# Exclusion patterns are evaluated in order
250
# Place most common exclusions first for better performance
251
exclude_patterns = [
252
"*.tmp", # Fast: simple extension match
253
"drafts/*", # Fast: single directory match
254
"**/temp/*", # Slower: recursive directory match
255
]
256
```
257
258
**CI Detection Caching:**
259
260
```python
261
# CI warnings are cached per repository
262
# Multiple files in same repo don't trigger repeated warnings
263
```
264
265
## Integration Examples
266
267
### Plugin Configuration with Exclusions
268
269
```yaml
270
plugins:
271
- git-revision-date-localized:
272
type: date
273
exclude:
274
- "drafts/*"
275
- "*.tmp"
276
- "generated/**/*"
277
fallback_to_build_date: true
278
strict: false
279
```
280
281
### Custom Exclusion Logic
282
283
```python
284
from mkdocs_git_revision_date_localized_plugin.exclude import exclude
285
286
def should_process_file(file_path, config):
287
"""Custom logic for determining file processing"""
288
exclusion_patterns = config.get("exclude", [])
289
290
# Use built-in exclusion
291
if exclude(file_path, exclusion_patterns):
292
return False
293
294
# Add custom logic
295
if file_path.startswith("api/") and not file_path.endswith(".md"):
296
return False
297
298
return True
299
```
300
301
### CI Environment Handling
302
303
```python
304
import os
305
from mkdocs_git_revision_date_localized_plugin.ci import is_shallow_clone, raise_ci_warnings
306
307
def configure_for_ci(config):
308
"""Adjust configuration for CI environments"""
309
if any(ci_var in os.environ for ci_var in ["CI", "GITHUB_ACTIONS", "GITLAB_CI"]):
310
# Enable fallback for CI environments
311
config["fallback_to_build_date"] = True
312
config["strict"] = False
313
314
# Check for shallow clone issues
315
if is_shallow_clone(repo):
316
raise_ci_warnings(repo)
317
318
return config
319
```