{"id":19147762,"url":"https://github.com/refcell/amble","last_synced_at":"2025-05-07T03:03:21.237Z","repository":{"id":201019781,"uuid":"706757977","full_name":"refcell/amble","owner":"refcell","description":"First class, scalable rust project generator with batteries included. ","archived":false,"fork":false,"pushed_at":"2023-11-16T13:45:52.000Z","size":3785,"stargazers_count":20,"open_issues_count":12,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-03T06:05:39.144Z","etag":null,"topics":["clap","cli","generator","rust","template"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/amble","language":"Rust","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/refcell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2023-10-18T15:01:00.000Z","updated_at":"2025-01-10T21:02:43.000Z","dependencies_parsed_at":"2024-11-09T07:52:40.012Z","dependency_job_id":"faf7e798-73dd-4ac6-ab1e-cd15f6db67d5","html_url":"https://github.com/refcell/amble","commit_stats":null,"previous_names":["refcell/amble"],"tags_count":62,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refcell%2Famble","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refcell%2Famble/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refcell%2Famble/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refcell%2Famble/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/refcell","download_url":"https://codeload.github.com/refcell/amble/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252804208,"owners_count":21806769,"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":["clap","cli","generator","rust","template"],"created_at":"2024-11-09T07:52:18.677Z","updated_at":"2025-05-07T03:03:20.912Z","avatar_url":"https://github.com/refcell.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# amble\n\n[![CI Build Status]][actions]\n[![Release]][actions]\n[![Tag Build Status]][actions]\n[![License]][mit-license]\n[![Docs]][Docs-rs]\n[![Latest Version]][crates.io]\n[![rustc 1.70+]][Rust 1.70]\n\n[CI Build Status]: https://img.shields.io/github/actions/workflow/status/refcell/amble/ci.yml?branch=main\u0026label=build\n[Tag Build Status]: https://img.shields.io/github/actions/workflow/status/refcell/amble/tag.yml?branch=main\u0026label=tag\n[Release]: https://img.shields.io/github/actions/workflow/status/refcell/amble/release.yml?branch=main\u0026label=release\n[actions]: https://github.com/refcell/amble/actions?query=branch%3Amain\n[Latest Version]: https://img.shields.io/crates/v/amble.svg\n[crates.io]: https://crates.io/crates/amble\n[rustc 1.70+]: https://img.shields.io/badge/rustc_1.70+-lightgray.svg?label=msrv\n[Rust 1.70]: https://blog.rust-lang.org/2023/06/01/Rust-1.70.0.html\n[License]: https://img.shields.io/badge/license-MIT-7795AF.svg\n[mit-license]: https://github.com/refcell/amble/blob/main/LICENSE.md\n[Docs-rs]: https://docs.rs/amble/\n[Docs]: https://img.shields.io/docsrs/amble.svg?color=319e8c\u0026label=docs.rs\n\n\n**First class, scalable rust project generator with batteries included.** Amble is https://github.com/refcell/amble/labels/stable\n\n![](./etc/banner.png)\n\n**[Install](#usage)**\n| [User Docs](#what-is-amble)\n| [Crate Docs][crates.io]\n| [Reference][Docs-rs]\n| [Contributing](#contributing)\n| [License](#license)\n\n## What is amble?\n\n`amble` is a cli application for generating rust projects\nwith batteries included. By using a workspace and\nsub-crates, `amble` scales to any number of crates.\n\nYou can think of `amble` as an extension of `cargo init`.\nCargo provides [convenience methods][c_new]\nfor generating new project structures, the two primary\ntypes being a library or a binary project. Below is an\nexample of the directory structure generated by\n`cargo init --lib`. (A binary project would only differ\nin having a `main.rs` file instead of `lib.rs`).\n\n```text\nproject\n├─ Cargo.toml\n└─ src\n   └─ lib.rs\n```\n\n`amble` provides a more extensive cli command for generating\nproject directory structures with [workspaces][Workspaces].\nLibrary sub-crates are nested inside the cannonical\n`crates/` directory, while binary crates are nested inside\nthe `bin/` directory. A top-level `Cargo.toml` file defines\na workspace including the binaries and libraries as well as\nshared package metadata and dependencies, minimizing\ninconsistencies across the sub-crates. `amble` also exposes\nthe `--lib` and `--bin` flags which fallback to `cargo init`\nand create the default `cargo init` file structure with all\n`amble` batteries included and available through cli flags.\n\nBelow is an example waterfall directory structure output\nfor when `amble` is run with the argument `project` as\nthe project name.\n\n```text\nproject\n├─ Cargo.toml\n├─ bin\n│  └─ example\n│     ├─ Cargo.toml\n│     └─ src\n│        └─ main.rs\n└─ crates\n   └─ common\n      ├─ Cargo.toml\n      └─ src\n         └─ lib.rs\n```\n\n*As detailed in [Usage](#usage) below, this output is generated by running `amble project --dry-run`.*\n\n[c_new]: https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/cargo_new.rs\n[Workspaces]: https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html\n\n## Usage\n\nInstall `amble` using cargo.\n\n```text\ncargo install amble\n```\n\nAlternatively, `amble` can be built from source.\n\n```text\ngit clone git@github.com:refcell/amble.git \u0026\u0026 cd amble\ncargo build --release\n```\n\nTo run `amble`, it is recommended to first run it in dry mode which will print\na waterfall directory structure for the files that would be created when run\nwithout dry mode. Simply run `amble \u003cproject_name\u003e --dry-run`, where `\u003cproject_name\u003e`\nis the name of the project/directory you want to create.\n\nBy default, `amble` uses the current directory for the project name, so it\nis perfectly acceptable to run `amble --dry-run`, which will just use `.`\nas the project path. *Note, amble will exit if it finds cargo artifacts\nin the directory you chose to execute in.*\n\nTo run `amble` out of dry mode, just run `amble`!\n\nA pre-defined github action ci workflow can be automatically generated by\npassing in the `--with-ci` flag to `amble`. This would generate a directory\nstructure as follows (`amble --dry-run --with-ci`).\n\n```text\n.\n├─ Cargo.toml\n├─ bin\n│  └─ example\n│     ├─ Cargo.toml\n│     └─ src\n│        └─ main.rs\n├─ crates\n│  └─ common\n│     ├─ Cargo.toml\n│     └─ src\n│        └─ lib.rs\n└─ .github\n   └─ workflows\n      └─ ci.yml\n```\n\nAmble also provides fallthrough methods for generating\n`cargo init` library and binary projects with batteries such as\na templated readme, github action ci workflows, and licensing.\nThe flags to pass through to `cargo init` operations are injective,\nmeaning `amble --bin` will pass through to `cargo init --bin` and\n`amble --lib` will pass through to `cargo init --lib`. As usual,\nany other valid amble flag can be provided along with the `--lib`\nand `--bin` flags.\n\n#### CLI Flags\n\nBelow is an inexhaustive list of the main cli flags.\nThese are subject to change and new ones can be added.\nTo view a more up-to-date list, run the `amble --help` command locally.\n\n```text\nFirst class, scalable rust project generator with batteries included.\n\nUsage: amble [OPTIONS] [PROJECT_DIR]\n\nArguments:\n  [PROJECT_DIR]  The path to the project directory. By default, the current working directory is used. If any rust artifacts are detected in the specified or unspecified directory, an error will be thrown [default: .]\n\nOptions:\n  -v, --v...                         Verbosity level (0-4)\n      --dry-run                      Dry run mode. If this flag is provided, the cli will not execute commands, printing the directories and files that would be created instead\n      --overwrite                    Overwrite existing files. If this flag is provided, the cli will overwrite existing files\n      --bare                         Bare mode. Only for `--bin` and `--lib` flags. If specified, generated files will be the basic `cargo init` files\n  -n, --name \u003cNAME\u003e                  The project name. This will be used for the binary application name [default: example]\n  -w, --with-ci                      Add github actions ci workflow\n  -c, --ci-yml \u003cCI_YML\u003e              Copy the specified ci workflow file to the project's `.github/workflows/` directory\n  -a, --authors \u003cAUTHORS\u003e            Override the project authors\n  -b, --bin                          Builds a cargo binary project\n  -l, --lib                          Builds a cargo library project\n      --without-readme               Prevents a readme from being generated\n      --full                         Full generates a full project structure including license, ci, gitignore, etc\n      --etc                          Adds an `etc/` directory to the project. This _Et Cetera_ directory is used for storing miscellaneous files\n      --assets                       Adds template assets to the `etc/` directory of the generate project. Will be run automatically if the `--full` flag is provided\n      --license                      Adds an MIT License to the project. The MIT License type can be overridden with the `--with-license` flag\n      --gitignore                    Adds a Gitignore file to the project\n  -d, --description \u003cDESCRIPTION\u003e    Specifies the description of the project in the top-level `Cargo.toml` workspace\n      --dependencies \u003cDEPENDENCIES\u003e  Adds these dependencies to the top-level `Cargo.toml` workspace alongside the default dependencies\n      --list                         Lists the default dependencies\n      --with-license \u003cWITH_LICENSE\u003e  License Override. This will override the default MIT License. The license type must be a valid SPDX license identifier\n  -h, --help                         Print help\n  -V, --version                      Print version\n```\n\n*You can generate this output by running `amble --help`.*\n\n## Contributing\n\nAll contributions are welcome! Experimentation is highly encouraged and new issues are welcome.\n\n## Troubleshooting \u0026 Bug Reports\n\nPlease check existing issues for similar bugs or\n[open an issue](https://github.com/refcell/amble/issues/new)\nif no relevant issue already exists.\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE.md).\nFree and open-source, forever.\n*All our rust are belong to you.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frefcell%2Famble","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frefcell%2Famble","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frefcell%2Famble/lists"}