|
| 1 | +# Package Enrichment |
| 2 | + |
| 3 | +git-pkgs can fetch additional metadata about your dependencies from the [ecosyste.ms Packages API](https://packages.ecosyste.ms/). This powers the `outdated` and `licenses` commands. |
| 4 | + |
| 5 | +## outdated |
| 6 | + |
| 7 | +Show packages that have newer versions available in their registries. |
| 8 | + |
| 9 | +``` |
| 10 | +$ git pkgs outdated |
| 11 | +lodash 4.17.15 -> 4.17.21 (patch) |
| 12 | +express 4.17.0 -> 4.19.2 (minor) |
| 13 | +webpack 4.46.0 -> 5.90.3 (major) |
| 14 | +
|
| 15 | +3 outdated packages: 1 major, 1 minor, 1 patch |
| 16 | +``` |
| 17 | + |
| 18 | +Major updates are shown in red, minor in yellow, patch in cyan. |
| 19 | + |
| 20 | +### Options |
| 21 | + |
| 22 | +``` |
| 23 | +-e, --ecosystem=NAME Filter by ecosystem |
| 24 | +-r, --ref=REF Git ref to check (default: HEAD) |
| 25 | +-f, --format=FORMAT Output format (text, json) |
| 26 | + --major Show only major version updates |
| 27 | + --minor Show only minor or major updates (skip patch) |
| 28 | + --stateless Parse manifests directly without database |
| 29 | +``` |
| 30 | + |
| 31 | +### Examples |
| 32 | + |
| 33 | +Show only major updates: |
| 34 | + |
| 35 | +``` |
| 36 | +$ git pkgs outdated --major |
| 37 | +webpack 4.46.0 -> 5.90.3 (major) |
| 38 | +``` |
| 39 | + |
| 40 | +Check a specific release: |
| 41 | + |
| 42 | +``` |
| 43 | +$ git pkgs outdated v1.0.0 |
| 44 | +``` |
| 45 | + |
| 46 | +JSON output: |
| 47 | + |
| 48 | +``` |
| 49 | +$ git pkgs outdated -f json |
| 50 | +``` |
| 51 | + |
| 52 | +## licenses |
| 53 | + |
| 54 | +Show licenses for dependencies with optional compliance checks. |
| 55 | + |
| 56 | +``` |
| 57 | +$ git pkgs licenses |
| 58 | +lodash MIT (npm) |
| 59 | +express MIT (npm) |
| 60 | +request Apache-2.0 (npm) |
| 61 | +``` |
| 62 | + |
| 63 | +### Options |
| 64 | + |
| 65 | +``` |
| 66 | +-e, --ecosystem=NAME Filter by ecosystem |
| 67 | +-r, --ref=REF Git ref to check (default: HEAD) |
| 68 | +-f, --format=FORMAT Output format (text, json, csv) |
| 69 | + --allow=LICENSES Comma-separated list of allowed licenses |
| 70 | + --deny=LICENSES Comma-separated list of denied licenses |
| 71 | + --permissive Only allow permissive licenses (MIT, Apache, BSD, etc.) |
| 72 | + --copyleft Flag copyleft licenses (GPL, AGPL, etc.) |
| 73 | + --unknown Flag packages with unknown/missing licenses |
| 74 | + --group Group output by license |
| 75 | + --stateless Parse manifests directly without database |
| 76 | +``` |
| 77 | + |
| 78 | +### Compliance Checks |
| 79 | + |
| 80 | +Only allow permissive licenses: |
| 81 | + |
| 82 | +``` |
| 83 | +$ git pkgs licenses --permissive |
| 84 | +lodash MIT (npm) |
| 85 | +express MIT (npm) |
| 86 | +gpl-pkg GPL-3.0 (npm) [copyleft] |
| 87 | +
|
| 88 | +1 license violation found |
| 89 | +``` |
| 90 | + |
| 91 | +Explicit allow list: |
| 92 | + |
| 93 | +``` |
| 94 | +$ git pkgs licenses --allow=MIT,Apache-2.0 |
| 95 | +``` |
| 96 | + |
| 97 | +Deny specific licenses: |
| 98 | + |
| 99 | +``` |
| 100 | +$ git pkgs licenses --deny=GPL-3.0,AGPL-3.0 |
| 101 | +``` |
| 102 | + |
| 103 | +Flag packages with no license information: |
| 104 | + |
| 105 | +``` |
| 106 | +$ git pkgs licenses --unknown |
| 107 | +``` |
| 108 | + |
| 109 | +### Output Formats |
| 110 | + |
| 111 | +Group by license: |
| 112 | + |
| 113 | +``` |
| 114 | +$ git pkgs licenses --group |
| 115 | +MIT (45) |
| 116 | + lodash |
| 117 | + express |
| 118 | + ... |
| 119 | +
|
| 120 | +Apache-2.0 (12) |
| 121 | + request |
| 122 | + ... |
| 123 | +``` |
| 124 | + |
| 125 | +CSV for spreadsheets: |
| 126 | + |
| 127 | +``` |
| 128 | +$ git pkgs licenses -f csv > licenses.csv |
| 129 | +``` |
| 130 | + |
| 131 | +JSON for scripting: |
| 132 | + |
| 133 | +``` |
| 134 | +$ git pkgs licenses -f json |
| 135 | +``` |
| 136 | + |
| 137 | +### Exit Codes |
| 138 | + |
| 139 | +The licenses command exits with code 1 if any violations are found. This makes it suitable for CI pipelines: |
| 140 | + |
| 141 | +```yaml |
| 142 | +- run: git pkgs licenses --stateless --permissive |
| 143 | +``` |
| 144 | +
|
| 145 | +### License Categories |
| 146 | +
|
| 147 | +Permissive licenses (allowed with `--permissive`): |
| 148 | +MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, Unlicense, CC0-1.0, 0BSD, WTFPL, Zlib, BSL-1.0 |
| 149 | + |
| 150 | +Copyleft licenses (flagged with `--copyleft` or `--permissive`): |
| 151 | +GPL-2.0, GPL-3.0, LGPL-2.1, LGPL-3.0, AGPL-3.0, MPL-2.0 (and their variant identifiers) |
| 152 | + |
| 153 | +## Data Source |
| 154 | + |
| 155 | +Both commands fetch package metadata from [ecosyste.ms](https://packages.ecosyste.ms/), which aggregates data from npm, RubyGems, PyPI, Cargo, and other package registries. |
| 156 | + |
| 157 | +## Caching |
| 158 | + |
| 159 | +Package metadata is cached in the pkgs.sqlite3 database. Each package tracks when it was last enriched, and stale data (older than 24 hours) is automatically refreshed on the next query. |
| 160 | + |
| 161 | +The cache stores: |
| 162 | +- Latest version number |
| 163 | +- License (SPDX identifier) |
| 164 | +- Description |
| 165 | +- Homepage URL |
| 166 | +- Repository URL |
| 167 | + |
| 168 | +## Stateless Mode |
| 169 | + |
| 170 | +Both commands support `--stateless` mode, which parses manifest files directly from git without requiring a database. This is useful in CI environments where you don't want to run `git pkgs init` first. |
| 171 | + |
| 172 | +``` |
| 173 | +$ git pkgs outdated --stateless |
| 174 | +$ git pkgs licenses --stateless --permissive |
| 175 | +``` |
| 176 | +
|
| 177 | +In stateless mode, package metadata is fetched fresh each time and cached only in memory for the duration of the command. |
0 commit comments