Skip to content

Commit dc399b6

Browse files
bitwise-aidenbitwise-aiden
committed
Update README.md to reflect gem + annotation change
1 parent c0c28b7 commit dc399b6

File tree

1 file changed

+44
-89
lines changed

1 file changed

+44
-89
lines changed

‎README.md

+44-89
Original file line numberDiff line numberDiff line change
@@ -40,10 +40,9 @@ Tapioca makes it easy to work with [Sorbet](https://sorbet.org) in your codebase
4040
* [Excluding a gem from RBI generation](#excluding-a-gem-from-rbi-generation)
4141
* [Changing the strictness level of the RBI for a gem](#changing-the-strictness-level-of-the-rbi-for-a-gem)
4242
* [Keeping RBI files for gems up-to-date](#keeping-rbi-files-for-gems-up-to-date)
43-
* [Pulling RBI annotations from remote sources](#pulling-rbi-annotations-from-remote-sources)
43+
* [Pulling RBI annotations from remote sources](#pulling-rbi-annotations-from-remote-sources)
4444
* [Basic authentication](#basic-authentication)
4545
* [Using a .netrc file](#using-a-netrc-file)
46-
* [Changing the typed strictness of annotations files](#changing-the-typed-strictness-of-annotations-files)
4746
* [Generating RBI files for Rails and other DSLs](#generating-rbi-files-for-rails-and-other-dsls)
4847
* [Keeping RBI files for DSLs up-to-date](#keeping-rbi-files-for-dsls-up-to-date)
4948
* [Writing custom DSL compilers](#writing-custom-dsl-compilers)
@@ -72,7 +71,7 @@ $ tapioca help
7271

7372
Commands:
7473
tapioca --version, -v # Show version
75-
tapioca annotations # Pull gem RBI annotations from remote sources
74+
tapioca annotations # Deprecated, this command has been merged into `tapioca gem`. Please use that instead.
7675
tapioca check-shims # Check duplicated definitions in shim RBIs
7776
tapioca configure # Initialize folder structure and type checking configuration
7877
tapioca dsl [constant...] # Generate RBIs for dynamic methods
@@ -192,6 +191,15 @@ Options:
192191
# Default: development
193192
[--halt-upon-load-error], [--no-halt-upon-load-error] # Halt upon a load error while loading the Rails application
194193
# Default: true
194+
[--annotations], [--no-annotations] # Include RBI annotations from remote source
195+
# Default: true
196+
[--annotation-sources=one two three] # URIs of the sources to pull gem RBI annotations from
197+
# Default: ["https://raw.githubusercontent.com/Shopify/rbi-central/main"]
198+
[--annotation-netrc], [--no-annotation-netrc] # Use .netrc to authenticate to private annotation sources
199+
# Default: true
200+
[--annotation-netrc-file=ANNOTATION_NETRC_FILE] # Path to .netrc file
201+
[--annotation-auth=ANNOTATION_AUTH] # HTTP authorization header for private annotation sources
202+
[--exclude-annotation=gem [gem ...]] # Excludes annotation for gem while generating RBI
195203
-c, [--config=<config file path>] # Path to the Tapioca configuration file
196204
# Default: sorbet/tapioca/config.yml
197205
-V, [--verbose], [--no-verbose] # Verbose output for debugging purposes
@@ -321,67 +329,28 @@ Nothing to do, all RBIs are up-to-date.
321329
322330
This option can be used on CI to make sure the RBI files are always up-to-date and ensure accurate type checking. **Warning**: doing so will break your normal Dependabot workflow as every pull-request opened to bump a gem version will fail CI since the RBI will be out-of-date and will require you to manually run `bin/tapioca gems` to update them.
323331
324-
### Pulling RBI annotations from remote sources
325-
326-
Since Tapioca does not perform any type inference, the RBI files generated for the gems do not contain any type signatures. Instead, Tapioca relies on the community to provide high-quality, manually written RBI annotations for public gems.
327-
328-
To pull the annotations relevant to your project from the central repository, run the `annotations` command:
332+
#### Pulling RBI annotations from remote sources
329333
330-
```shell
331-
$ bin/tapioca annotations
332-
333-
Retrieving index from central repository... Done
334-
Listing gems from Gemfile.lock... Done
335-
Removing annotations for gems that have been removed... Nothing to do
336-
Fetching gem annotations from central repository...
334+
Since Tapioca does not perform any type inference, the RBI files generated for the gems do not contain any type signatures. Instead, Tapioca relies on the community to provide high-quality, manually written RBI annotations for public gems. These annotations are sourced and combined with the generated RBIs as a step during `tapioca gem`.
337335
338-
Fetched activesupport
339-
created sorbet/rbi/annotations/activesupport.rbi
340-
341-
Done
342-
```
336+
By default, Tapioca will pull the annotations stored in the central repository located at https://github.com/Shopify/rbi-central. It is possible to use a custom repository by changing the value of the `--annotation-sources` option. For example if your repository is stored on Github:
343337
344-
<!-- START_HELP_COMMAND_ANNOTATIONS -->
345338
```shell
346-
$ tapioca help annotations
347-
348-
Usage:
349-
tapioca annotations
350-
351-
Options:
352-
[--sources=one two three] # URIs of the sources to pull gem RBI annotations from
353-
# Default: ["https://raw.githubusercontent.com/Shopify/rbi-central/main"]
354-
[--netrc], [--no-netrc] # Use .netrc to authenticate to private sources
355-
# Default: true
356-
[--netrc-file=NETRC_FILE] # Path to .netrc file
357-
[--auth=AUTH] # HTTP authorization header for private sources
358-
--typed, -t, [--typed-overrides=gem:level [gem:level ...]] # Override for typed sigils for pulled annotations
359-
-c, [--config=<config file path>] # Path to the Tapioca configuration file
360-
# Default: sorbet/tapioca/config.yml
361-
-V, [--verbose], [--no-verbose] # Verbose output for debugging purposes
362-
363-
Pull gem RBI annotations from remote sources
364-
```
365-
<!-- END_HELP_COMMAND_ANNOTATIONS -->
366-
367-
By default, Tapioca will pull the annotations stored in the central repository located at https://github.com/Shopify/rbi-central. It is possible to use a custom repository by changing the value of the `--sources` options. For example if your repository is stored on Github:
368-
369-
```shell
370-
$ bin/tapioca annotations --sources https://raw.githubusercontent.com/$USER/$REPO/$BRANCH
339+
$ bin/tapioca gem --annotation-sources https://raw.githubusercontent.com/$USER/$REPO/$BRANCH
371340
```
372341
373342
Tapioca also supports pulling annotations from multiple sources:
374343
375344
```shell
376-
$ bin/tapioca annotations --sources https://raw.githubusercontent.com/$USER/$REPO1/$BRANCH https://raw.githubusercontent.com/$USER/$REPO2/$BRANCH
345+
$ bin/tapioca gem --annotation-sources https://raw.githubusercontent.com/$USER/$REPO1/$BRANCH https://raw.githubusercontent.com/$USER/$REPO2/$BRANCH
377346
```
378347
379348
#### Basic authentication
380349
381350
Private repositories can be used as sources by passing the option `--auth` with an authentication string. For Github, this string is `token $TOKEN` where `$TOKEN` is a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token):
382351
383352
```shell
384-
$ bin/tapioca annotations --sources https://raw.githubusercontent.com/$USER/$PRIVATE_REPO/$BRANCH --auth "token $TOKEN"
353+
$ bin/tapioca gem --annotation-sources https://raw.githubusercontent.com/$USER/$PRIVATE_REPO/$BRANCH --annotation-auth "token $TOKEN"
385354
```
386355
387356
#### Using a .netrc file
@@ -396,38 +365,21 @@ machine raw.githubusercontent.com
396365
password $TOKEN
397366
```
398367
399-
where `$USERNAME` is your Github username and `$TOKEN` is a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token), then, if you run Tapioca with the `--netrc` option (enabled by default), your annotation requests should be authenticated properly.
368+
where `$USERNAME` is your Github username and `$TOKEN` is a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token), then, if you run Tapioca with the `--annotation-netrc` option (enabled by default), your annotation requests should be authenticated properly.
400369
401-
The `--netrc-file` option can be specified to read from a file other than `~/.netrc`:
370+
The `--annotation-netrc-file` option can be specified to read from a file other than `~/.netrc`:
402371
403372
```shell
404-
$ bin/tapioca annotations --netrc-file /path/to/my/netrc/file
373+
$ bin/tapioca gem --annotation-netrc-file /path/to/my/netrc/file
405374
```
406375
407-
Similar to `--netrc-file`, you can also specify an alternative netrc file by using the `TAPIOCA_NETRC_FILE` environment variable:
376+
Similar to `--annotation-netrc-file`, you can also specify an alternative netrc file by using the `TAPIOCA_NETRC_FILE` environment variable:
408377
409378
```shell
410-
$ TAPIOCA_NETRC_FILE=/path/to/my/netrc/file bin/tapioca annotations
379+
$ TAPIOCA_NETRC_FILE=/path/to/my/netrc/file bin/tapioca gem
411380
```
412381
413-
Tapioca will first try to find the netrc file as specified by the `--netrc-file` option. If that option is not supplied, it will try the `TAPIOCA_NETRC_FILE` environment variable value. If that value is not supplied either, it will fallback to `~/.netrc`.
414-
415-
#### Changing the typed strictness of annotations files
416-
417-
Sometimes the annotations files pulled by Tapioca will create type errors in your project because of incompatibilities.
418-
It is possible to ignore such files by switching their strictness level `--typed-overrides` option:
419-
420-
```shell
421-
$ bin/tapioca annotations --typed-overrides gemA:ignore gemB:false
422-
```
423-
424-
Or through the configuration file:
425-
426-
```yaml
427-
annotations:
428-
typed_overrides:
429-
gemA: "ignore"
430-
gemB: "false"
382+
Tapioca will first try to find the netrc file as specified by the `--annotation-netrc-file` option. If that option is not supplied, it will try the `TAPIOCA_NETRC_FILE` environment variable value. If that value is not supplied either, it will fallback to `~/.netrc`.
431383
```
432384
433385
### Generating RBI files for Rails and other DSLs
@@ -805,7 +757,6 @@ Loading Sorbet payload... Done
805757
Loading shim RBIs from sorbet/rbi/shims... Done
806758
Loading gem RBIs from sorbet/rbi/gems... Done
807759
Loading gem RBIs from sorbet/rbi/dsl... Done
808-
Loading annotation RBIs from sorbet/rbi/annotations... Done
809760
Looking for duplicates... Done
810761
811762
Duplicated RBI for ::MyModel#title:
@@ -829,22 +780,20 @@ Usage:
829780
tapioca check-shims
830781
831782
Options:
832-
[--gem-rbi-dir=GEM_RBI_DIR] # Path to gem RBIs
833-
# Default: sorbet/rbi/gems
834-
[--dsl-rbi-dir=DSL_RBI_DIR] # Path to DSL RBIs
835-
# Default: sorbet/rbi/dsl
836-
[--shim-rbi-dir=SHIM_RBI_DIR] # Path to shim RBIs
837-
# Default: sorbet/rbi/shims
838-
[--annotations-rbi-dir=ANNOTATIONS_RBI_DIR] # Path to annotations RBIs
839-
# Default: sorbet/rbi/annotations
840-
[--todo-rbi-file=TODO_RBI_FILE] # Path to the generated todo RBI file
841-
# Default: sorbet/rbi/todo.rbi
842-
[--payload], [--no-payload] # Check shims against Sorbet's payload
843-
# Default: true
844-
-w, [--workers=N] # Number of parallel workers (default: auto)
845-
-c, [--config=<config file path>] # Path to the Tapioca configuration file
846-
# Default: sorbet/tapioca/config.yml
847-
-V, [--verbose], [--no-verbose] # Verbose output for debugging purposes
783+
[--gem-rbi-dir=GEM_RBI_DIR] # Path to gem RBIs
784+
# Default: sorbet/rbi/gems
785+
[--dsl-rbi-dir=DSL_RBI_DIR] # Path to DSL RBIs
786+
# Default: sorbet/rbi/dsl
787+
[--shim-rbi-dir=SHIM_RBI_DIR] # Path to shim RBIs
788+
# Default: sorbet/rbi/shims
789+
[--todo-rbi-file=TODO_RBI_FILE] # Path to the generated todo RBI file
790+
# Default: sorbet/rbi/todo.rbi
791+
[--payload], [--no-payload] # Check shims against Sorbet's payload
792+
# Default: true
793+
-w, [--workers=N] # Number of parallel workers (default: auto)
794+
-c, [--config=<config file path>] # Path to the Tapioca configuration file
795+
# Default: sorbet/tapioca/config.yml
796+
-V, [--verbose], [--no-verbose] # Verbose output for debugging purposes
848797
849798
Check duplicated definitions in shim RBIs
850799
```
@@ -918,11 +867,17 @@ gem:
918867
rbi_max_line_length: 120
919868
environment: development
920869
halt_upon_load_error: true
870+
annotations: true
871+
annotation_sources:
872+
- https://raw.githubusercontent.com/Shopify/rbi-central/main
873+
annotation_netrc: true
874+
annotation_netrc_file: ''
875+
annotation_auth: ''
876+
exclude_annotation: []
921877
check_shims:
922878
gem_rbi_dir: sorbet/rbi/gems
923879
dsl_rbi_dir: sorbet/rbi/dsl
924880
shim_rbi_dir: sorbet/rbi/shims
925-
annotations_rbi_dir: sorbet/rbi/annotations
926881
todo_rbi_file: sorbet/rbi/todo.rbi
927882
payload: true
928883
workers: 1

0 commit comments

Comments
 (0)