{"id":13877951,"url":"https://github.com/drwl/annotaterb","last_synced_at":"2025-05-15T02:06:02.192Z","repository":{"id":37883798,"uuid":"503606323","full_name":"drwl/annotaterb","owner":"drwl","description":"A Ruby Gem that adds annotations to your Rails models and route files.","archived":false,"fork":false,"pushed_at":"2025-04-11T02:04:47.000Z","size":2100,"stargazers_count":361,"open_issues_count":38,"forks_count":42,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-05-05T16:46:50.333Z","etag":null,"topics":["activerecord","annotations","rails","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/drwl.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-06-15T03:50:52.000Z","updated_at":"2025-05-05T15:29:22.000Z","dependencies_parsed_at":"2024-05-08T21:45:20.137Z","dependency_job_id":"1fe9557f-dfa4-47b4-816e-b5a7035dee9a","html_url":"https://github.com/drwl/annotaterb","commit_stats":{"total_commits":924,"total_committers":244,"mean_commits":"3.7868852459016393","dds":0.8322510822510822,"last_synced_commit":"7746f54b31674603b671db2433cd3d2e3da78fb7"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drwl%2Fannotaterb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drwl%2Fannotaterb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drwl%2Fannotaterb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drwl%2Fannotaterb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/drwl","download_url":"https://codeload.github.com/drwl/annotaterb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254259370,"owners_count":22040819,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["activerecord","annotations","rails","ruby"],"created_at":"2024-08-06T08:01:35.806Z","updated_at":"2025-05-15T02:06:02.160Z","avatar_url":"https://github.com/drwl.png","language":"Ruby","readme":"## AnnotateRb\n### forked from the [Annotate aka AnnotateModels gem](https://github.com/ctran/annotate_models)\n\nA Ruby Gem that adds annotations to your Rails models and route files.\n\n----------\n[![CI](https://github.com/drwl/annotaterb/actions/workflows/ci.yml/badge.svg)](https://github.com/drwl/annotaterb/actions/workflows/ci.yml)\n[![Gem Version](https://badge.fury.io/rb/annotaterb.svg)](https://badge.fury.io/rb/annotaterb)\n\nAdds comments summarizing the model schema or routes in your:\n\n- ActiveRecord models\n- Fixture files\n- Tests and Specs\n- FactoryBot factories\n- `routes.rb` file (for Rails projects)\n\nThe schema comment looks like this:\n\n```ruby\n# == Schema Information\n#\n# Table name: tasks\n#\n#  id         :integer          not null, primary key\n#  content    :string\n#  count      :integer\n#  status     :boolean\n#  created_at :datetime         not null\n#  updated_at :datetime         not null\n#\nclass Task \u003c ApplicationRecord\n  ...\n```\n----------\n## Installation\n\n```sh\n$ gem install annotaterb\n```\n\nOr install it into your Rails project through the Gemfile:\n\n```rb\ngroup :development do\n  ...\n\n  gem \"annotaterb\"\n  \n  ...\n```\n\n### Automatically annotate models\nFor Rails projects, model files can get automatically annotated after migration tasks. To do this, run the following command:\n\n```sh\n$ bin/rails g annotate_rb:install\n```\n\nThis will copy a rake task into your Rails project's `lib/tasks` directory that will hook into the Rails project rake tasks, automatically running AnnotateRb after database migration rake tasks.\n\nTo skip the automatic annotation that happens after a db task, pass the environment variable `ANNOTATERB_SKIP_ON_DB_TASKS=1` before your command.\n\n```sh\n$ ANNOTATERB_SKIP_ON_DB_TASKS=1 bin/rails db:migrate\n```\n\n### Added Rails generators\nThe following Rails generator commands get added.\n\n```sh\n$ bin/rails generator --help\n\n...\n\nAnnotateRb:\n  annotate_rb:config\n  annotate_rb:hook\n  annotate_rb:install\n  annotate_rb:update_config\n...\n\n```\n\n`bin/rails g annotate_rb:config`\n- Generates a new configuration file, `.annotaterb.yml`, using defaults from the gem.\n\n`bin/rails g annotate_rb:hook`\n- Installs the Rake file to automatically annotate Rails models on a database task (e.g. AnnotateRb will automatically run after running `bin/rails db:migrate`).\n\n`bin/rails g annotate_rb:install`\n- Runs the `config` and `hook` generator commands\n\n`bin/rails g annotate_rb:update_config`\n- Appends to `.annotaterb.yml` any configuration key-value pairs that are used by the Gem. This is useful when there's a drift between the config file values and the gem defaults (i.e. when new features get added).\n\n## Migrating from the annotate gem\nRefer to the [migration guide](MIGRATION_GUIDE.md).\n\n## Usage\n\nAnnotateRb has a CLI that you can use to add or remove annotations.\n\n```sh\n# To show the CLI options\n$ bundle exec annotaterb \n\nUsage: annotaterb [command] [options]\n\nCommands:\n    models [options]\n    routes [options]\n    help\n    version\n\nOptions:\n    -v, --version                    Display the version..\n    -h, --help                       You're looking at it.\n\nAnnotate model options:\n    Usage: annotaterb models [options]\n\n    -a, --active-admin               Annotate active_admin models\n        --show-migration             Include the migration version number in the annotation\n    -k, --show-foreign-keys          List the table's foreign key constraints in the annotation\n        --ck, --complete-foreign-keys\n                                     Complete foreign key names in the annotation\n    -i, --show-indexes               List the table's database indexes in the annotation\n    -s, --simple-indexes             Concat the column's related indexes in the annotation\n        --hide-limit-column-types VALUES\n                                     don't show limit for given column types, separated by commas (i.e., `integer,boolean,text`)\n        --hide-default-column-types VALUES\n                                     don't show default for given column types, separated by commas (i.e., `json,jsonb,hstore`)\n        --ignore-unknown-models      don't display warnings for bad model files\n    -I, --ignore-columns REGEX       don't annotate columns that match a given REGEX (i.e., `annotate -I '^(id|updated_at|created_at)'`\n        --with-comment               include database comments in model annotations\n\nAnnotate routes options:\n    Usage: annotaterb routes [options]\n\n        --ignore-routes REGEX        don't annotate routes that match a given REGEX (i.e., `annotate -I '(mobile|resque|pghero)'`\n        --timestamp                  Include timestamp in (routes) annotation\n        --w, --wrapper STR           Wrap annotation with the text passed as parameter.\n                                     If --w option is used, the same text will be used as opening and closing\n        --wo, --wrapper-open STR     Annotation wrapper opening.\n        --wc, --wrapper-close STR    Annotation wrapper closing\n\nCommand options:\nAdditional options that work for annotating models and routes\n\n        --additional-file-patterns path1,path2,path3\n                                     Additional file paths or globs to annotate, separated by commas (e.g. `/foo/bar/%model_name%/*.rb,/baz/%model_name%.rb`)\n    -d, --delete                     Remove annotations from all model files or the routes.rb file\n        --model-dir dir              Annotate model files stored in dir rather than app/models, separate multiple dirs with commas\n        --root-dir dir               Annotate files stored within root dir projects, separate multiple dirs with commas\n        --ignore-model-subdirects    Ignore subdirectories of the models directory\n        --sort                       Sort columns alphabetically, rather than in creation order\n        --classified-sort            Sort columns alphabetically, but first goes id, then the rest columns, then the timestamp columns and then the association columns\n    -R, --require path               Additional file to require before loading models, may be used multiple times\n    -e [tests,fixtures,factories,serializers],\n        --exclude                    Do not annotate fixtures, test files, factories, and/or serializers\n    -f [bare|rdoc|yard|markdown],    Render Schema Information as plain/RDoc/Yard/Markdown\n        --format\n    -p [before|top|after|bottom],    Place the annotations at the top (before) or the bottom (after) of the model/test/fixture/factory/route/serializer file(s)\n        --position\n        --pc, --position-in-class [before|top|after|bottom]\n                                     Place the annotations at the top (before) or the bottom (after) of the model file\n        --pf, --position-in-factory [before|top|after|bottom]\n                                     Place the annotations at the top (before) or the bottom (after) of any factory files\n        --px, --position-in-fixture [before|top|after|bottom]\n                                     Place the annotations at the top (before) or the bottom (after) of any fixture files\n        --pt, --position-in-test [before|top|after|bottom]\n                                     Place the annotations at the top (before) or the bottom (after) of any test files\n        --pr, --position-in-routes [before|top|after|bottom]\n                                     Place the annotations at the top (before) or the bottom (after) of the routes.rb file\n        --ps, --position-in-serializer [before|top|after|bottom]\n                                     Place the annotations at the top (before) or the bottom (after) of the serializer files\n        --force                      Force new annotations even if there are no changes.\n        --debug                      Prints the options and outputs messages to make it easier to debug.\n        --frozen                     Do not allow to change annotations. Exits non-zero if there are going to be changes to files.\n        --trace                      If unable to annotate a file, print the full stack trace, not just the exception message.\n```\n\n## Configuration\n\n### Storing default options\nPreviously in the [Annotate](https://github.com/ctran/annotate_models) you could pass options through the CLI or store them as environment variables. Annotaterb removes dependency on the environment variables and instead can read values from a `.annotaterb.yml` file stored in the Rails project root.\n\n```yml\n# .annotaterb.yml\n\nposition: after\n```\n\nAnnotaterb reads first from the configuration file, if it exists, then merges it with any options passed into the CLI. \n\nFor further details visit the [section in the migration guide](MIGRATION_GUIDE.md#automatic-annotations-after-running-database-migration-commands).\n\n### How to skip annotating a particular model\nIf you want to always skip annotations on a particular model, add this string\nanywhere in the file:\n\n    # -*- SkipSchemaAnnotations\n\n## Sorting\n\nBy default, columns will be sorted in database order (i.e. the order in which\nmigrations were run).\n\nIf you prefer to sort alphabetically so that the results of annotation are\nconsistent regardless of what order migrations are executed in, use `--sort`.\n\n## License\n\nReleased under the same license as Ruby. No Support. No Warranty.\n","funding_links":[],"categories":["Ruby","Documentation","Gems"],"sub_categories":["Database Structure and Schema Management"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrwl%2Fannotaterb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrwl%2Fannotaterb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrwl%2Fannotaterb/lists"}