{"id":29279456,"url":"https://github.com/ishad0w/amvm","last_synced_at":"2026-01-31T13:45:55.972Z","repository":{"id":300766409,"uuid":"1006846107","full_name":"ishad0w/amvm","owner":"ishad0w","description":"Ansible with Mitogen Version Manager","archived":false,"fork":false,"pushed_at":"2025-10-24T09:01:01.000Z","size":9,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-24T10:22:30.742Z","etag":null,"topics":["ansible","bash-scripting","linux","macos","mitogen","python3","venv","version-manager"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/ishad0w.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-23T04:51:20.000Z","updated_at":"2025-10-24T09:01:04.000Z","dependencies_parsed_at":"2025-06-23T14:27:05.523Z","dependency_job_id":"24f83560-61f9-4bd9-869f-f8aff8110f4f","html_url":"https://github.com/ishad0w/amvm","commit_stats":null,"previous_names":["ishad0w/amvm"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/ishad0w/amvm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ishad0w%2Famvm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ishad0w%2Famvm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ishad0w%2Famvm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ishad0w%2Famvm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ishad0w","download_url":"https://codeload.github.com/ishad0w/amvm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ishad0w%2Famvm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28944789,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-31T13:02:32.153Z","status":"ssl_error","status_checked_at":"2026-01-31T13:00:07.528Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["ansible","bash-scripting","linux","macos","mitogen","python3","venv","version-manager"],"created_at":"2025-07-05T14:00:50.605Z","updated_at":"2026-01-31T13:45:55.966Z","avatar_url":"https://github.com/ishad0w.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# `amvm` _(Ansible with Mitogen Version Manager)_\n\n`amvm` is a simple, powerful shell script for managing multiple versions of Ansible + Mitogen in isolated Python virtual environments (`venv`) and switching between them seamlessly.\n\nIt's designed for Ansible developers and operators who need to work with different versions for different projects without the hassle of manually managing virtual environments or `ansible.cfg` files.\n\n## Why `amvm`?\n\nIf you've ever found yourself juggling multiple Ansible projects, you've likely faced these challenges:\n\n- Forgetting to activate the correct environment, leading to dependency errors.\n- Managing different `ansible.cfg` files for standard vs. Mitogen-enabled runs.\n- Manually creating and activating Python `venv`s for each version (`source .../activate`).\n\n`amvm` solves these problems by automating the entire workflow.\nIt's more than just a `venv` wrapper; it's a complete management tool that lets you **set your Ansible version once and forget about it**.\n\n## Features\n`amvm` provides flexibility and speed through a set of powerful, integrated features:\n\n-   🚀 **Atomic Version \u0026 Config Switching**: This is the core feature. A single `amvm` command lets you switch both the active `ansible` version **and** its corresponding configuration (`ansible.cfg`) in one atomic operation. Instantly toggle between a standard setup, a Mitogen-optimized one, or your own project-specific config without any manual file editing. No more `source .../activate` or juggling symlinks.\n\n-   💻 **Fast Interactive UI**: Switch between any version and config combination in seconds using a modern, interactive menu powered by `fzf` (if installed), with a simple numbered menu as a fallback.\n\n-   ⚡ **Integrated Mitogen \u0026 Custom Configs**:\n    -   **Mitogen Support**: `amvm` automatically creates a Mitogen-ready configuration when installed. This appears as a separate option in the menu (e.g., `ansible-11.7.0 (mitogen)`), letting you enable or disable Mitogen with a single keystroke.\n    -   **Per-Environment Configs**: Drop an `ansible-customized.cfg` file into any version's directory, and `amvm` automatically offers it as a switching option (e.g., `ansible-11.7.0 (custom)`)—perfect for project-specific settings.\n\n-   🔧 **Extensive Customization**:\n    -   **Custom Versions**: Easily define your own version sets (Ansible, ansible-core, ansible-lint, Mitogen) in a simple configuration file (`~/.amvm.cfg`).\n    -   **Custom Root Directory**: Change the default installation path (`~/.amvm`) to anywhere on your system.\n\n-   📦 **Batteries-Included Installation**: Each environment is created with not just Ansible, but also common dependencies like `ansible-lint`, `boto3`, `pywinrm`, and `jmespath`, saving you setup time. You can easily skip optional packages.\n\n-   🛡️ **Safe and Clean Management**:\n    -   **Isolated Environments**: Each version lives in its own `venv`, preventing any dependency conflicts.\n    -   **Interactive Uninstall**: Safely remove specific versions with a confirmation prompt.\n    -   **Total Cleanup**: A single `amvm --cleanup` command interactively removes all `amvm`-managed files and directories.\n\n-   🏠 **Self-Contained**: All environments, shims, and configurations are stored in a single directory (`~/.amvm` by default), making backups or removal trivial.\n\n## Prerequisites\n-   **Compatibility**: Works on **Linux** and **macOS**.\n-   **Bash**: Version `3.2` or newer.\n-   **Python 3**: The `python3` command must be available in your `PATH`.\n-   **Python Venv Module**: The module for creating virtual environments is required.\n-   **`curl`**: Required to download the script.\n-   **`fzf`** (Optional but Recommended): For the best interactive menu experience.\n\n## Version Matrix\n`amvm` installs specific, tested combinations of packages. To use other versions, define them in your `~/.amvm.cfg`. To skip installing `ansible-lint` or `mitogen`, use `0` as the version number.\n\n| Key |  `ansible` | `ansible-core` | `ansible-lint` | `mitogen` |\n|:---:|:----------:|:--------------:|:--------------:|:---------:|\n| `10` |  `10.7.0`  |    `2.17.14`   |    `26.1.1`    |  `0.3.39` |\n| `11` |  `11.13.0` |    `2.18.13`   |    `26.1.1`    |  `0.3.39` |\n| `12` |  `12.3.0`  |    `2.19.6`    |    `26.1.1`    |  `0.3.39` |\n| `13` |  `13.3.0`  |    `2.20.2`    |    `26.1.1`    |  `0.3.39` |\n\n---\n\n## Installation\n\n1.  **Download the Script**\n    Place the `amvm` script in a directory that is already in your `$PATH`, such as `~/.local/bin`.\n\n    ```bash\n    # Create the directory if it doesn't exist\n    mkdir -p ~/.local/bin\n    \n    # Download and make executable\n    curl -Lo ~/.local/bin/amvm https://raw.githubusercontent.com/ishad0w/amvm/main/amvm\n    chmod +x ~/.local/bin/amvm\n    ```\n\n2.  **Configure Your PATH**\n    `amvm` works by creating symlinks (shims) to the `ansible*` executables in `~/.amvm/bin`. For your system to find these shims, you must add this directory to your `$PATH`. **This is a one-time setup step.**\n\n    The script will remind you if your `PATH` is not configured and will provide the exact command to run.\n\n    For **zsh**:\n    ```bash\n    echo 'export PATH=\"$HOME/.amvm/bin:$PATH\"' \u003e\u003e ~/.zshrc\n    ```\n\n    For **bash**:\n    ```bash\n    echo 'export PATH=\"$HOME/.amvm/bin:$PATH\"' \u003e\u003e ~/.bashrc\n    ```\n\n    After running the command, **restart your terminal** or source your profile (`source ~/.zshrc`) to apply the changes.\n\n---\n\n## Usage\n\n### 1. Install an Environment\nUse the `amvm --install` command. You can install a specific predefined version or all of them.\n\n```bash\n# Install a specific built-in version (e.g., 11)\namvm --install 11\n\n# Install all available built-in versions\namvm --install all\n```\n\n### 2. Switch the Active Version (it's not activated by default)\nRun `amvm` with no arguments to open the interactive selection menu.\n\n**With `fzf`:**\n```\namvm\u003e\n┌───────────────────────────┐\n│ \u003e ansible-11.7.0 (mitogen)│\n│   ansible-11.7.0          │\n│   ansible-10.7.0 (mitogen)│\n│   ansible-10.7.0 (custom) │\n│   ansible-10.7.0          │\n└───────────────────────────┘\n```\n\n**Without `fzf` (fallback):**\n```\n   1) ansible-11.7.0 (mitogen)\n   2) ansible-11.7.0\n   3) ansible-10.7.0 (mitogen)\n   4. ansible-10.7.0 (custom)\n   5. ansible-10.7.0\nEnter a number: _\n```\n\nAfter switching, you can immediately verify the change:\n```bash\n$ ansible --version\nansible [core 2.18.6]\n  config file = /home/user/.ansible.cfg\n  ...\n```\n\n### 3. Uninstall an Environment\nUse `amvm --uninstall` to open an interactive menu to select and remove a version.\n\n```\nuninstall\u003e\n┌──────────────────┐\n│ \u003e ansible-11.7.0 │\n│   ansible-10.7.0 │\n└──────────────────┘\n```\n\nYou will be asked for confirmation before anything is deleted.\n\n### Management Commands\n\n```bash\namvm --install \u003c10, 11 | all\u003e     # Install a built-in version (e.g., 10, 11) or all\namvm --install-custom \u003ckey\u003e  # Install a user-defined version from your config\namvm --uninstall             # Interactively remove an installed version\namvm --list                  # List all installed versions\namvm --cleanup               # Interactively remove ALL amvm data\namvm --help, -h              # Show the help message\namvm --version, -v           # Show amvm version\n```\n\n---\n\n## Customization\n\nYou can configure `amvm` by creating a file at `~/.amvm.cfg`.\n\n### 1. Defining Custom Versions\n\nTo install versions not built into `amvm`, define them in `~/.amvm.cfg` using a Bash array named `AMVM_CUSTOM_VERSIONS`.\nEach entry is a string with the format: `\"KEY:ansible|ansible-core|ansible-lint|mitogen\"`.\n\n**Use `0` to skip installing `ansible-lint` or `mitogen`**.\n\n**Example `~/.amvm.cfg`:**\n```bash\n# Define your custom versions here\nAMVM_CUSTOM_VERSIONS=(\n  # Key '9': Ansible 9 with Mitogen, but no ansible-lint\n  \"9:9.5.1|2.16.7|0|0.3.18\"\n  # Key '8': Ansible 8 without any optional packages\n  \"8:8.7.0|2.15.10|0|0\"\n)\n```\n\nWith this config, you can now run:\n```bash\namvm --install-custom 9\namvm --install-custom 8\n```\n\n### 2. Using a Custom `ansible.cfg`\n\nFor ultimate control, you can use your own hand-tuned `ansible.cfg` for any version.\nSimply create a file named `ansible-customized.cfg` inside the desired environment's directory:\n\n`~/.amvm/ansible-X.Y.Z/ansible-customized.cfg`\n\nThe next time you run `amvm`, a new `(custom)` option will automatically appear in the menu for that version, allowing you to switch to it instantly.\n\n### 3. Changing the Root Directory\n\nYou can change the main directory where `amvm` stores everything by setting `AMVM_ROOT` in your config.\n\n```bash\n# ~/.amvm.cfg\nAMVM_ROOT=\"/opt/ansible_versions\"\n```\n\n---\n\n## How It Works\n\n-   **`~/.amvm/`**: The root directory for everything `amvm` manages.\n    -   `ansible-X.Y.Z/`: Each environment is a self-contained Python `venv`. It contains `ansible.cfg`, `ansible-mitogen.cfg` (if applicable), and your own `ansible-customized.cfg`.\n    -   `bin/`: This directory contains the \"shims\" (symlinks) pointing to executables in the **currently active** environment. This is the directory you add to your `PATH`.\n-   **`~/.ansible.cfg`**: This is not a real file, but a symlink that always points to the active configuration file (`ansible.cfg`, `ansible-mitogen.cfg`, or `ansible-customized.cfg`) inside the active environment.\n\nThis shim-based approach is what makes switching seamless and eliminates the need to `source` or `deactivate` environments.\n\n---\n\n## Troubleshooting\n\n-   **`amvm: command not found`**\n    Ensure the `amvm` script is in a directory listed in your `PATH` (like `~/.local/bin`) and that it has execute permissions (`chmod +x amvm`).\n\n-   **`ansible: command not found` after switching**\n    Your `PATH` is likely misconfigured. Run `amvm` and it will show a warning with the exact command needed to fix your shell profile file. Remember to **restart your terminal** after making the change.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fishad0w%2Famvm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fishad0w%2Famvm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fishad0w%2Famvm/lists"}