{"id":13529150,"url":"https://github.com/com-lihaoyi/Ammonite","last_synced_at":"2025-04-01T15:30:47.838Z","repository":{"id":25740726,"uuid":"29178282","full_name":"com-lihaoyi/Ammonite","owner":"com-lihaoyi","description":"Scala Scripting","archived":false,"fork":false,"pushed_at":"2024-10-24T01:38:52.000Z","size":535603,"stargazers_count":2609,"open_issues_count":153,"forks_count":370,"subscribers_count":64,"default_branch":"main","last_synced_at":"2024-10-29T15:09:12.787Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://ammonite.io","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/com-lihaoyi.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","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},"funding":{"github":"lihaoyi"}},"created_at":"2015-01-13T07:34:38.000Z","updated_at":"2024-10-28T16:24:40.000Z","dependencies_parsed_at":"2024-04-09T09:29:43.448Z","dependency_job_id":"4f254c52-d5f6-415b-9cd2-7f9a339880ab","html_url":"https://github.com/com-lihaoyi/Ammonite","commit_stats":null,"previous_names":["lihaoyi/ammonite"],"tags_count":147,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/com-lihaoyi%2FAmmonite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/com-lihaoyi%2FAmmonite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/com-lihaoyi%2FAmmonite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/com-lihaoyi%2FAmmonite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/com-lihaoyi","download_url":"https://codeload.github.com/com-lihaoyi/Ammonite/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246662248,"owners_count":20813716,"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-08-01T07:00:33.767Z","updated_at":"2025-04-01T15:30:42.828Z","avatar_url":"https://github.com/com-lihaoyi.png","language":"Scala","funding_links":["https://github.com/sponsors/lihaoyi","https://www.patreon.com/lihaoyi"],"categories":["Shells","Containers \u0026 Language Extentions \u0026 Linting","Scala","Packages","Table of Contents"],"sub_categories":["Base Shells","For Scala","Shells","Extensions"],"readme":"# Ammonite [![Build Status][travis-badge]][travis-link] [![Build (Windows)][appveyor-badge]][appveyor-link] [![Gitter Chat][gitter-badge]][gitter-link] [![Patreon][patreon-badge]][patreon-link]\n\n[travis-badge]: https://travis-ci.org/lihaoyi/Ammonite.svg\n[travis-link]: https://travis-ci.org/lihaoyi/Ammonite\n[appveyor-badge]: https://ci.appveyor.com/api/projects/status/github/lihaoyi/Ammonite\n[appveyor-link]: https://ci.appveyor.com/project/lihaoyi/ammonite\n[gitter-badge]: https://badges.gitter.im/Join%20Chat.svg\n[gitter-link]: https://gitter.im/lihaoyi/Ammonite?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge\n[patreon-badge]: https://img.shields.io/badge/patreon-sponsor-ff69b4.svg\n[patreon-link]: https://www.patreon.com/lihaoyi\n\nThis is where the code for the [Ammonite](https://ammonite.io) \nproject lives:\n\n- [Ammonite-REPL](https://ammonite.io), the improved Scala REPL\n\nIf you use Ammonite and like it, you will probably enjoy the following book by the Author:\n\n- [*Hands-on Scala Programming*](https://www.handsonscala.com/)\n\n*Hands-on Scala* has uses Ammonite extensively throughout the book, using\nAmmonite to accomplish a lot of useful tasks: exploring third party libraries or\nwriting parallel web-crawlers in the REPL, and implementing entire programming\nlanguages in Ammonite Scala Scripts. *Hands-on Scala* is a great way to level \nup your skills in Scala in general and Ammonite in particular.\n\nIf you want to learn more about Ammonite or how to use it, check out the links \nabove, or ask on the [Gitter Channel](https://gitter.im/lihaoyi/Ammonite). The \nremainder of this document is developer-docs for people who want to work on the \nAmmonite source code itself.\n\nIf you are interested in living more \"on the edge\", we also publish artifacts \nand the doc-site every commit; the doc-site is available at\n\n- https://ammonite.io/#UnstableVersions\n\nAnd contains instructions on how to download the per-commit executable or \ndepend on the per-commit maven artifact.\n\nIf you use Ammonite and like it, please support us by donating to our Patreon:\n\n- [https://www.patreon.com/lihaoyi](https://www.patreon.com/lihaoyi)\n\n# Developer Docs\n\nThe layout of the repository is roughly:\n\n- `amm/` is [Ammonite](https://ammonite.io)'s core, REPL and script runner\n- `terminal/` is the JLine re-implementation used by Ammonite-REPL to provide \n  syntax highlighting and multiline editing\n- `readme/` is the source code for the [Documentation](https://ammonite.io/#Ammonite-Ops), \n  written in [Scalatex](https://www.lihaoyi.com/Scalatex/).\n- `published/` is a synthetic project used for publishing, excluding the readme \n  and integration tests\n\nFor more detailed information, check out the internals documentation for \nhigh-level overviews of some interesting facets of the codebase\n\n- [Internals Documentation](https://github.com/com-lihaoyi/Ammonite/tree/main/internals-docs)\n\n## Common Commands\n\n### Manual Testing\n\nAlthough most features should be unit tested, it's still useful to fire up a REPL from the current codebase to see things work (or not). There are a variety of shells you can spin up for testing different things:\n\n- `mill -i -w terminal[2.12.6].test.run` is useful for manual testing the\n  terminal interaction; it basically contains a minimal echo-anything terminal,\n  with multiline input based on the count of open- and closed-parentheses. This\n  lets you test all terminal interactions without all the complexity of the\n  Scala compiler, classloaders, etc. that comes in `repl/`\n  \n- `mill -i -w amm[2.12.6].run` brings up the Ammonite-REPL using the source code\n  in the repository, and automatically restarts it on-exit if you have made a\n  change to the code. Useful for manual testing both of `amm/` as well as\n  `ops/`, since you can just `import ammonite.ops._` and start using them. Note\n  that this does not bring in filesystem utilities like the `wd` variable, `cd!`\n  command. You can also pass in the path to a `.sc` file to run it using\n  Ammonite's script runner\n  \n- `mill -i -w integration[2.12.6].test.run` runs the trivial main method in the\n  `integration` subproject, letting you manually test running Ammonite\n  programmatically, whether through `run` or `debug`\n\n- `mill -i amm[2.12.6].assembly` creates an assembly at\n  `out/amm/2.12.6/assembly/dest/out.jar` that you can then use to test: start a\n  REPL, run scripts, etc. in a standalone environment without being wrapped in\n  Mill build tool\n\n- `mill -i amm[2.12.6].launcher` creates a launcher script at\n  `out/amm/2.12.6/launcher/dest/run` that can also be used to run Ammonite\n  outside of the Mill build tool.\n\n### Automated Testing\n\nWhile working on an arbitrary `xyz` subproject, `mill -w xyz.test` runs tests after every change.\n`./mill 'amm[2.13.8].test'` can be a bit slow because of the amount of code it compiles, so you may want to specify the test manually via `./mill 'amm[2.13.8].test path.to.test'`.\n\n- `./mill -i 'amm[2.13.8].test'` tests the Ammonite Script-runner, without filesystem-shell integration.\n- `./mill -i 'amm.repl[2.13.8].test'` tests the Ammonite-REPL.\n- `./mill -i 'terminal[2.13.8].test'` tests the readline re-implementation: keyboard navigation, shortcuts, editing, without any filesystem/scala-repl logic\n- `./mill -i 'integration[2.13.8].test'` kicks off the integration tests, which bundle `amm/` and `shell/` into their respective jars and invoke them as subprocesses. Somewhat slow, but exercises all the command-line-parsing stuff that the other unit tests do not exercise, and makes sure that everything works when run from `.jar`s instead of loose class-files\n- `./mill -i 'sshd[2.13.8].test'` tests the remote Ammonite-REPL over sshd.\n\n### Publishing\n\n- Publishing is automatic, controlled by scripts in the `ci/` folder.\n\n- Every commit that lands in main will publish a new\n  [unstable version](https://ammonite.io/#UnstableVersions),\n  that you can already use and download. This includes publishing the unstable version\n  to maven central to the\n  [snapshot-commit-uploads](https://github.com/com-lihaoyi/Ammonite/releases/tag/snapshot-commit-uploads)\n  tag, and updating the documentation-site so it's\n  [Unstable Version](https://ammonite.io/#UnstableVersions) download\n  instructions to point to it, though the \"main\" download/install instructions\n  in the doc-site will not be changed.\n\n- Every commit that lands in main *with a tag* will re-publish a stable version\n  to maven central and upload a new versioned release (using the tag as the\n  version) and the doc-site is updated so the main download/install instructions\n  point at the new published stable version.\n\nIn general, if you land a change in main, once CI completes (1-2hrs) you\nshould be able to download it via the\n[Unstable Version](https://ammonite.io/#UnstableVersions)\ninstructions and make use of your changes standalone or in an SBT project.\n\nOccasionally, the CI job building and publishing one of the above steps\nflakes and fails, and needs to be re-run through the travis web interface.\n\n## Issue Tags\n\nI've started tagging open issues in the issue tracker to try and keep things neat. This is what the various tags mean:\n\nEach issue should only have one of these:\n\n- `bug`: this behavior clearly wrong, and needs to be fixed\n- `enhancement`: something relatively speccable, that can be worked on, finished, and will make Ammonite better\n- `wishlist`: could be totally awesome, but we're uncertain if it is worth doing at all, what it would look like, or if it will ever reach a \"finished\" state.\n\nAnd possibly:\n\n- `help wanted`: I don't have context, hardware, or for some other reason am unlikely to ever do this. But I know people out there care, so one of you should step up and fix it.\n\n## Contribution Guidelines\n\n- **All code PRs should come with**: a meaningful description, inline-comments for important things, unit tests (positive and negative), and a green build in [CI](https://travis-ci.org/lihaoyi/Ammonite)\n- **Try to keep lines below 80 characters width**, with a hard limit of 100 characters.\n- **PRs for features should generally come with *something* added to the [Documentation](https://ammonite.io)**, so people can discover that it exists\n- **Be prepared to discuss/argue-for your changes if you want them merged**! You will probably need to refactor so your changes fit into the larger codebase\n- **If your code is hard to unit test, and you don't want to unit test it, that's ok**. But be prepared to argue why that's the case!\n- **It's entirely possible your changes won't be merged**, or will get ripped out later. This is also the case for my changes, as the Author!\n- **Even a rejected/reverted PR is valuable**! It helps to explore the solution space, and know what works and what doesn't. For every line in the repo, at least three lines were tried, committed, and reverted/refactored, and more than 10 were tried without committing.\n- **Feel free to send Proof-Of-Concept PRs** that you don't intend to get merged.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcom-lihaoyi%2FAmmonite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcom-lihaoyi%2FAmmonite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcom-lihaoyi%2FAmmonite/lists"}