flox-sharing

# Flox Environment Sharing & Composition Guide

## Core Concepts

**Composition**: Build-time merging of environments (deterministic)
**Remote Environments**: Shared environments via FloxHub
**Team Collaboration**: Reusable, shareable environment stacks

## Understanding Environment Sharing

**The `.flox/` directory contains the environment definition**:
- Package specifications and versions
- Environment variables
- Build definitions
- Hooks and services configuration

**The environment definition does NOT include**:
- Built binaries/artifacts (those are created by builds and can be published as packages)
- Local data or cache

**Two sharing mechanisms**:
1. **Git**: Commit `.flox/` directory to git. When used with development environments, this is typically alongside your source code in the same repository. Other developers clone the repo and get both the environment definition and source code.
2. **FloxHub**: Push environment definition only using `flox push`. This shares ONLY the `.flox/` directory, not any source code or other files. Useful for runtime environments or shared base environments used across multiple projects.

**This is different from publishing packages** (see **flox-publish** skill), where you build and distribute the actual binaries/artifacts.

## Core Commands

```bash
# Activate remote environment
flox activate -r owner/environment-name

# Pull remote environment locally
flox pull owner/environment-name

# Push local environment to FloxHub
flox push

# Compose environments in manifest
# (see [include] section below)
```

## Environment Composition

### Basic Composition

Merge environments at build time using `[include]`:

```toml
[include]
environments = [
    { remote = "team/postgres" },
    { remote = "team/redis" },
    { remote = "team/python-base" }
]
```

### Creating Composition-Optimized Environments

**Design for clean merging at build time:**

```toml
[install]
# Use pkg-groups to prevent conflicts
gcc.pkg-path = "gcc"
gcc.pkg-gro