Skip to content

Commit 3534d07

Browse files
CopilotCopilot
authored
docs: make usage.md exhaustive — add all CLI flags, config keys, and GitLab token snippet
1 parent d5e221c commit 3534d07

1 file changed

Lines changed: 144 additions & 17 deletions

File tree

‎docs/usage.md‎

Lines changed: 144 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,21 @@ poetry run rsmetacheck --input https://github.com/tidyverse/tidyverse
1212

1313
### Analyze a Specific Branch
1414

15+
Use `--branch` (short: `-b`) to target a non-default branch:
16+
1517
```bash
1618
poetry run rsmetacheck --input https://github.com/tidyverse/tidyverse --branch develop
1719
```
1820

19-
### Analyze Multiple Repositories from a JSON File
21+
### Analyze Multiple Repositories
22+
23+
Pass several URLs directly on the command line:
24+
25+
```bash
26+
poetry run rsmetacheck --input https://github.com/example/repo_1 https://github.com/example/repo_2
27+
```
2028

21-
Create a `repositories.json` file:
29+
Or create a `repositories.json` file and pass it as the input:
2230

2331
```json
2432
{
@@ -29,48 +37,146 @@ Create a `repositories.json` file:
2937
}
3038
```
3139

32-
Run the analysis:
33-
3440
```bash
3541
poetry run rsmetacheck --input repositories.json
3642
```
3743

44+
### Customize Output Paths
45+
46+
By default RSMetaCheck writes its output to the current working directory. Use the flags below to redirect any of the outputs:
47+
48+
| Flag | Default | Description |
49+
|------|---------|-------------|
50+
| `--somef-output` | `./somef_outputs` | Directory for raw SoMEF JSON files |
51+
| `--pitfalls-output` | `./pitfalls_outputs` | Directory for per-repository pitfall JSON-LD files |
52+
| `--analysis-output` | `./analysis_results.json` | File for the overall summary report |
53+
| `--notes-output` | *(not created)* | File for minor version-discrepancy notes (see below) |
54+
55+
```bash
56+
poetry run rsmetacheck --input repositories.json \
57+
--somef-output ./results/somef \
58+
--pitfalls-output ./results/pitfalls \
59+
--analysis-output ./results/summary.json \
60+
--notes-output ./results/notes.json
61+
```
62+
63+
### Version Discrepancy Notes
64+
65+
When a metadata version differs from the release version only slightly (every component differs by less than 2, e.g. `0.4.3.dev1` vs `0.4.2`), RSMetaCheck records a **note** instead of a full pitfall. Notes are only written when `--notes-output` is provided:
66+
67+
```bash
68+
poetry run rsmetacheck --input https://github.com/example/repo --notes-output ./notes.json
69+
```
70+
71+
Example notes file:
72+
73+
```json
74+
{
75+
"total_notes": 1,
76+
"notes": [
77+
{
78+
"repository": "example/repo",
79+
"file_name": "repo_output.json",
80+
"code": "P001",
81+
"note": "Version discrepancy: metadata '0.4.3.dev1' vs release '0.4.2'"
82+
}
83+
]
84+
}
85+
```
86+
87+
When the difference is significant (any component differs by 2 or more, e.g. `0.12.4` vs `0.12.1`), the issue is still reported as a pitfall regardless.
88+
89+
### Skip SoMEF and Analyze Existing Outputs
90+
91+
If you have already run SoMEF separately, pass `--skip-somef` and point `--input` at the existing JSON files to avoid re-running SoMEF:
92+
93+
```bash
94+
poetry run rsmetacheck --skip-somef --input somef_outputs/*.json
95+
```
96+
97+
Multiple glob patterns are supported:
98+
99+
```bash
100+
poetry run rsmetacheck --skip-somef --input my_somef_outputs_1/*.json my_somef_outputs_2/*.json
101+
```
102+
103+
### Verbose Output
104+
105+
By default, only detected pitfalls and warnings appear in the output JSON-LD files. Use `--verbose` to also include checks that passed:
106+
107+
```bash
108+
poetry run rsmetacheck --input https://github.com/tidyverse/tidyverse --verbose
109+
```
110+
111+
### SoMEF Confidence Threshold
112+
113+
Use `--threshold` to control how confident SoMEF must be before including a metadata field (default: `0.8`):
114+
115+
```bash
116+
poetry run rsmetacheck --input https://github.com/example/repo --threshold 0.6
117+
```
118+
119+
### Generate CodeMeta Files
120+
121+
Use `-c` / `--generate-codemeta` to instruct SoMEF to also produce a `codemeta.json` file for each repository:
122+
123+
```bash
124+
poetry run rsmetacheck --input https://github.com/example/repo --generate-codemeta
125+
```
126+
38127
### Configure Analysis Rules
39128

40-
RsMetaCheck can load a root-level `.rsmetacheck.toml` file to customize analysis behavior.
129+
RSMetaCheck automatically detects a `.rsmetacheck.toml` (or `rsmetacheck.toml`) file at the working directory. Alternatively, supply a custom path with `--config`:
130+
131+
```bash
132+
poetry run rsmetacheck --input https://github.com/example/repo --config ./ci/rsmetacheck.toml
133+
```
134+
135+
Supported configuration keys:
136+
137+
- `ignore` — list of pitfall/warning codes to skip (e.g. `"P001"`, `"W002"`)
138+
- `exclude_files` — glob patterns, filenames, or substrings of metadata sources to ignore
139+
- `parameters` — per-check tunable parameters
140+
- `active_profile` — name of the profile to activate automatically when no `--config-profile` flag is passed
141+
- `profiles` — named groups of overrides that can be selected at runtime
142+
143+
Full example:
41144

42145
```toml
43146
ignore = ["W002"]
44-
exclude_files = ["tmp_metadata.json"]
147+
exclude_files = ["**/generated/**", "tmp_metadata.json"]
148+
active_profile = "unstable"
45149

46150
[parameters.P001]
47-
ahead_significant_diff = 10
151+
ahead_significant_diff = 2
48152

49-
[profiles.prerelease]
50-
ignore = []
153+
[parameters.W002]
154+
stale_after_days = 3
51155

52156
[profiles.unstable]
53157
ignore = ["W002", "P017"]
54-
```
55158

56-
Use a profile:
159+
[profiles.unstable.parameters.P001]
160+
ahead_significant_diff = 10
57161

58-
```bash
59-
poetry run rsmetacheck --input https://github.com/example/repo --config-profile unstable
162+
[profiles.prerelease]
163+
ignore = []
164+
165+
[profiles.prerelease.parameters.P001]
166+
ahead_significant_diff = 1
60167
```
61168

62-
Use an explicit config path:
169+
Activate a profile from the command line (overrides `active_profile`):
63170

64171
```bash
65-
poetry run rsmetacheck --input https://github.com/example/repo --config ./ci/rsmetacheck.toml
172+
poetry run rsmetacheck --input https://github.com/example/repo --config-profile unstable
66173
```
67174

68175
## GitHub Action
69176

70-
You can integrate RSMetaCheck into your GitHub workflow to test your own repository and detect issues automatically.
177+
You can integrate RSMetaCheck into your GitHub workflow to test your own repository and detect issues automatically.
71178
Please refer to our action in the GitHub MarketPlace at [rsmetacheck actions](https://github.com/marketplace/actions/rsmetacheck) for more information.
72179

73-
74180
## GitLab CI/CD
75181

76182
You can integrate RSMetaCheck into your GitLab pipelines by adding the following snippet to your `.gitlab-ci.yml` file:
@@ -94,3 +200,24 @@ rsmetacheck:
94200
95201
`$CI_PROJECT_URL` is a [built-in GitLab CI/CD variable](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html) that automatically resolves to your repository's URL.
96202

203+
### Providing a GitHub Token (recommended)
204+
205+
SoMEF fetches repository metadata from GitHub's API. Without a token, anonymous requests are subject to low rate limits. Store your GitHub personal access token as a [GitLab CI/CD variable](https://docs.gitlab.com/ee/ci/variables/) named `GITHUB_TOKEN` and pass it to `somef configure`:
206+
207+
```yaml
208+
rsmetacheck:
209+
image: python:3.11
210+
stage: test
211+
script:
212+
- pip install rsmetacheck
213+
- somef configure -a -t $GITHUB_TOKEN
214+
- rsmetacheck --input $CI_PROJECT_URL
215+
artifacts:
216+
paths:
217+
- pitfalls_outputs/
218+
- somef_outputs/
219+
- analysis_results.json
220+
when: always
221+
expire_in: 1 week
222+
```
223+

0 commit comments

Comments
 (0)