{"id":13483262,"url":"https://github.com/thoughtbot/terrapin","last_synced_at":"2025-05-14T08:09:31.691Z","repository":{"id":28443931,"uuid":"117259518","full_name":"thoughtbot/terrapin","owner":"thoughtbot","description":"Run shell commands safely, even with user-supplied values","archived":false,"fork":false,"pushed_at":"2025-03-24T12:46:46.000Z","size":202,"stargazers_count":277,"open_issues_count":7,"forks_count":22,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-10T12:37:26.151Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/thoughtbot.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"thoughtbot"}},"created_at":"2018-01-12T15:50:55.000Z","updated_at":"2025-05-06T17:23:01.000Z","dependencies_parsed_at":"2024-05-01T08:52:38.383Z","dependency_job_id":"a307aafd-84c7-4784-8ae3-9f155b0b0385","html_url":"https://github.com/thoughtbot/terrapin","commit_stats":{"total_commits":190,"total_committers":44,"mean_commits":4.318181818181818,"dds":0.531578947368421,"last_synced_commit":"02a2f3e657b8ad891ee12f442820dbb36f63c571"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thoughtbot%2Fterrapin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thoughtbot%2Fterrapin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thoughtbot%2Fterrapin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thoughtbot%2Fterrapin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thoughtbot","download_url":"https://codeload.github.com/thoughtbot/terrapin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253568691,"owners_count":21928909,"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":[],"created_at":"2024-07-31T17:01:09.484Z","updated_at":"2025-05-14T08:09:31.631Z","avatar_url":"https://github.com/thoughtbot.png","language":"Ruby","readme":"# Terrapin\n\nRun shell commands safely, even with user-supplied values\n\n[API reference](http://rubydoc.info/gems/terrapin/)\n\n## Usage\n\nThe basic, normal stuff:\n\n```ruby\nline = Terrapin::CommandLine.new(\"echo\", \"hello 'world'\")\nline.command # =\u003e \"echo hello 'world'\"\nline.run # =\u003e \"hello world\\n\"\n```\n\nInterpolated arguments:\n\n```ruby\nline = Terrapin::CommandLine.new(\"convert\", \":in -scale :resolution :out\")\nline.command(in: \"omg.jpg\",\n             resolution: \"32x32\",\n             out: \"omg_thumb.jpg\")\n# =\u003e \"convert 'omg.jpg' -scale '32x32' 'omg_thumb.jpg'\"\n```\n\nIt prevents attempts at being bad:\n\n```ruby\nline = Terrapin::CommandLine.new(\"cat\", \":file\")\nline.command(file: \"haha`rm -rf /`.txt\") # =\u003e \"cat 'haha`rm -rf /`.txt'\"\n\nline = Terrapin::CommandLine.new(\"cat\", \":file\")\nline.command(file: \"ohyeah?'`rm -rf /`.ha!\") # =\u003e \"cat 'ohyeah?'\\\\''`rm -rf /`.ha!'\"\n```\n\nNOTE: It only does that for arguments interpolated via `run`, NOT arguments\npassed into `new` (see 'Security' below):\n\n```ruby\nline = Terrapin::CommandLine.new(\"echo\", \"haha`whoami`\")\nline.command # =\u003e \"echo haha`whoami`\"\nline.run # =\u003e \"hahawebserver\\n\"\n```\n\nThis is the right way:\n\n```ruby\nline = Terrapin::CommandLine.new(\"echo\", \"haha:whoami\")\nline.command(whoami: \"`whoami`\") # =\u003e \"echo haha'`whoami`'\"\nline.run(whoami: \"`whoami`\") # =\u003e \"haha`whoami`\\n\"\n```\n\nYou can ignore the result:\n\n```ruby\nline = Terrapin::CommandLine.new(\"noisy\", \"--extra-verbose\", swallow_stderr: true)\nline.command # =\u003e \"noisy --extra-verbose 2\u003e/dev/null\"\n\n# ... and on Windows...\nline.command # =\u003e \"noisy --extra-verbose 2\u003eNUL\"\n```\n\nIf your command errors, you get an exception:\n\n```ruby\nline = Terrapin::CommandLine.new(\"git\", \"commit\")\nbegin\n  line.run\nrescue Terrapin::ExitStatusError =\u003e e\n  e.message # =\u003e \"Command 'git commit' returned 1. Expected 0\"\nend\n```\n\nIf your command might return something non-zero, and you expect that, it's cool:\n\n```ruby\nline = Terrapin::CommandLine.new(\"/usr/bin/false\", \"\", expected_outcodes: [0, 1])\nbegin\n  line.run\nrescue Terrapin::ExitStatusError =\u003e e\n  # =\u003e You never get here!\nend\n```\n\nYou don't have the command? You get an exception:\n\n```ruby\nline = Terrapin::CommandLine.new(\"lolwut\")\nbegin\n  line.run\nrescue Terrapin::CommandNotFoundError =\u003e e\n  e # =\u003e the command isn't in the $PATH for this process.\nend\n```\n\nBut don't fear, you can specify where to look for the command:\n\n```ruby\nTerrapin::CommandLine.path = \"/opt/bin\"\nline = Terrapin::CommandLine.new(\"lolwut\")\nline.command # =\u003e \"lolwut\", but it looks in /opt/bin for it.\n```\n\nYou can even give it a bunch of places to look:\n\n```ruby\nFileUtils.rm(\"/opt/bin/lolwut\")\nFile.open('/usr/local/bin/lolwut') { |f| f.write('echo Hello') }\nTerrapin::CommandLine.path = [\"/opt/bin\", \"/usr/local/bin\"]\nline = Terrapin::CommandLine.new(\"lolwut\")\nline.run # =\u003e prints 'Hello', because it searches the path\n```\n\nOr just put it in the command:\n\n```ruby\nline = Terrapin::CommandLine.new(\"/opt/bin/lolwut\")\nline.command # =\u003e \"/opt/bin/lolwut\"\n```\n\nYou can see what's getting run. The 'Command' part it logs is in green for\nvisibility! (where applicable)\n\n```ruby\nline = Terrapin::CommandLine.new(\"echo\", \":var\", logger: Logger.new(STDOUT))\nline.run(var: \"LOL!\") # =\u003e Logs this with #info -\u003e Command :: echo 'LOL!'\n```\n\nOr log every command:\n\n```ruby\nTerrapin::CommandLine.logger = Logger.new(STDOUT)\nTerrapin::CommandLine.new(\"date\").run # =\u003e Logs this -\u003e Command :: date\n```\n\n## Security\n\nShort version: Only pass user-generated data into the `run` method and NOT\n`new`.\n\nAs shown in examples above, Terrapin will only shell-escape what is passed in as\ninterpolations to the `run` method. It WILL NOT escape what is passed in to the\nsecond argument of `new`. Terrapin assumes that you will not be manually\npassing user-generated data to that argument and will be using it as a template\nfor your command line's structure.\n\n## Runners\n\nTerrapin will choose from among a couple different ways of running commands.\nThe simplest is `Process.spawn`, which is also the default. Terrapin can also just use [backticks], so if for some reason you'd prefer that, you can ask Terrapin to use that:\n\n```ruby\nTerrapin::CommandLine.runner = Terrapin::CommandLine::BackticksRunner.new\n```\n\nAnd if you really want to, you can define your own Runner, though I can't imagine why you would.\n\n[backticks]: https://ruby-doc.org/3.2.1/Kernel.html#method-i-60\n\n```ruby\nTerrapin::CommandLine.runner = Terrapin::CommandLine::BackticksRunner.new\n```\n\nAnd if you really want to, you can define your own Runner, though I can't\nimagine why you would.\n\n### JRuby issues\n\n#### Caveat\n\nIf you get `Error::ECHILD` errors and are using JRuby, there is a very good\nchance that the error is actually in JRuby. This was brought to our attention\nin https://github.com/thoughtbot/terrapin/issues/24 and probably fixed in\nhttp://jira.codehaus.org/browse/JRUBY-6162. You *will* want to use the\n`BackticksRunner` if you are unable to update JRuby.\n\n#### Spawn warning\n\nIf you get `unsupported spawn option: out` warning (like in [issue\n38](https://github.com/thoughtbot/terrapin/issues/38)), try to use\n`PopenRunner`:\n\n```ruby\nTerrapin::CommandLine.runner = Terrapin::CommandLine::PopenRunner.new\n```\n\n## Thread Safety\n\nTerrapin should be thread safe. As discussed [here, in this climate_control\nthread](https://github.com/thoughtbot/climate_control/pull/11), climate_control,\nwhich modifies the environment under which commands are run for the\nBackticksRunner and PopenRunner, is thread-safe but not reentrant. Please let us\nknow if you find this is ever not the case.\n\n## Feedback\n\n*Security* concerns must be privately emailed to\n[security@thoughtbot.com](security@thoughtbot.com).\n\nQuestion? Idea? Problem? Bug? Comment? Concern? Like using question marks?\n\n[GitHub Issues For All!](https://github.com/thoughtbot/terrapin/issues)\n\n## Credits\n\nThank you to all [the\ncontributors](https://github.com/thoughtbot/terrapin/graphs/contributors)!\n\n## License\n\nCopyright © 2011 Jon Yurek and thoughtbot, inc. This is free software, and\nmay be redistributed under the terms specified in the\n[LICENSE](https://github.com/thoughtbot/terrapin/blob/master/LICENSE)\nfile.\n\n\u003c!-- START /templates/footer.md --\u003e\n## About thoughtbot\n\n![thoughtbot](https://thoughtbot.com/thoughtbot-logo-for-readmes.svg)\n\nThis repo is maintained and funded by thoughtbot, inc.\nThe names and logos for thoughtbot are trademarks of thoughtbot, inc.\n\nWe love open source software!\nSee [our other projects][community].\nWe are [available for hire][hire].\n\n[community]: https://thoughtbot.com/community?utm_source=github\n[hire]: https://thoughtbot.com/hire-us?utm_source=github\n\n\n\u003c!-- END /templates/footer.md --\u003e\n","funding_links":["https://github.com/sponsors/thoughtbot"],"categories":["Ruby","CLI Builder"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthoughtbot%2Fterrapin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthoughtbot%2Fterrapin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthoughtbot%2Fterrapin/lists"}