# mix-add

A global CLI tool for adding dependencies to Elixir projects without manually editing `mix.exs`. Built with [Igniter](https://hexdocs.pm/igniter) for safe and reliable code modifications.

## Features

- ✨ Add dependencies without manually editing `mix.exs`
- 🔍 Automatically fetch latest versions from Hex.pm
- 🎯 Support for Git, GitHub, and local path dependencies
- 🔧 Environment-specific dependencies (dev, test, prod)
- 🚀 Works from any directory in your project
- ⚡ Built on Igniter for safe AST-based modifications

## Installation

### As a global escript (Recommended)

```bash
# Clone and build
git clone https://github.com/hoangbits/mix-add.git
cd mix-add
mix deps.get
mix escript.build

# Install globally
mix escript.install

# Or install directly from Hex (once published)
mix escript.install hex mix_add_cli
```

### As a project dependency

Add to your `mix.exs`:

```elixir
{:mix_add_cli, "~> 1.0", only: [:dev]}
```

Then run:
```bash
mix deps.get
```

## Usage

### Global CLI (after escript installation)

```bash
# Add latest version
mix-add phoenix

# Add specific version
mix-add phoenix "~> 1.7"

# Add to specific environments
mix-add excoveralls --only dev,test

# Add from GitHub
mix-add my_lib --github username/my_lib

# Add from Git with branch
mix-add my_lib --git https://github.com/user/lib.git --branch main

# Add local dependency
mix-add my_lib --path ../my_lib

# Override existing dependency
mix-add phoenix "~> 1.7.10" --override
```

### As Mix task (when installed as dependency)

```bash
mix add phoenix "~> 1.7"
```

## Options

- `--version`, `-v` - Specify version constraint (default: latest from hex.pm)
- `--only` - Comma-separated list of environments (dev,test,prod)
- `--runtime` - Include in runtime (default: true)
- `--git` - Git repository URL
- `--github` - GitHub repository (username/repo format)
- `--path` - Local path dependency
- `--branch` - Git branch
- `--tag` - Git tag
- `--ref` - Git ref
- `--override` - Override existing dependency
- `--organization` - Hex organization
- `--repo` - Hex repository (default: hexpm)

## Examples

### Common use cases

```bash
# Add a standard Hex package
mix-add tesla

# Add with specific version
mix-add ecto "~> 3.11"

# Development-only dependency
mix-add dialyxir --only dev

# Test dependencies
mix-add mock "~> 0.3" --only test

# Multiple environments
mix-add phoenix_live_reload --only dev,test

# Exclude from runtime
mix-add inch_ex --only dev --runtime false
```

### Git dependencies

```bash
# From GitHub
mix-add my_package --github elixir-lang/my_package

# From Git URL with branch
mix-add my_package --git https://gitlab.com/user/package.git --branch develop

# With specific tag
mix-add my_package --github user/package --tag v1.0.0

# With commit ref
mix-add my_package --git https://github.com/user/package.git --ref abc123
```

### Local dependencies

```bash
# Relative path
mix-add my_local_lib --path ../my_local_lib

# Absolute path
mix-add my_local_lib --path /Users/me/projects/my_local_lib
```

### Umbrella projects

The tool automatically detects umbrella projects and finds the nearest `mix.exs`:

```bash
# From any subdirectory
cd apps/my_app/lib/some/deep/path
mix-add phoenix  # Will find and update apps/my_app/mix.exs
```

## How it works

1. **Finds `mix.exs`**: Searches current directory and up to 5 parent levels
2. **Fetches version**: If not specified, queries Hex.pm for latest stable version
3. **Modifies AST**: Uses Igniter to safely modify the Elixir AST
4. **Preserves formatting**: Maintains your existing code style
5. **Shows notice**: Reminds you to run `mix deps.get`

## Development

```bash
# Clone the repository
git clone https://github.com/hoangbits/mix-add.git
cd mix-add

# Install dependencies
mix deps.get

# Run tests
mix test

# Build escript
mix escript.build

# Test locally
./mix_add_cli phoenix
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

MIT License - see [LICENSE](LICENSE) file for details

## Credits

Built with [Igniter](https://github.com/ash-project/igniter) by the Ash Project team.

## Author

[hoangbits](https://github.com/hoangbits)