{"id":46678288,"url":"https://github.com/scinddev/xcind","last_synced_at":"2026-03-08T23:15:56.780Z","repository":{"id":343053042,"uuid":"1175614270","full_name":"scinddev/xcind","owner":"scinddev","description":"Docker Compose Project Wrapper","archived":false,"fork":false,"pushed_at":"2026-03-08T19:58:11.000Z","size":25,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-08T20:08:50.051Z","etag":null,"topics":["composer","docker","docker-compose"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scinddev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2026-03-08T00:01:27.000Z","updated_at":"2026-03-08T19:58:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/scinddev/xcind","commit_stats":null,"previous_names":["scinddev/xcind"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/scinddev/xcind","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scinddev%2Fxcind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scinddev%2Fxcind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scinddev%2Fxcind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scinddev%2Fxcind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scinddev","download_url":"https://codeload.github.com/scinddev/xcind/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scinddev%2Fxcind/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30274975,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-08T20:45:49.896Z","status":"ssl_error","status_checked_at":"2026-03-08T20:45:49.525Z","response_time":56,"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":["composer","docker","docker-compose"],"created_at":"2026-03-08T23:15:56.718Z","updated_at":"2026-03-08T23:15:56.775Z","avatar_url":"https://github.com/scinddev.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Xcind — Docker Compose Project Wrapper\n\nXcind is a slim shell wrapper around `docker compose` that automatically resolves\ncompose files, environment files, and override variants based on a per-project\nconfiguration file (`.xcind.sh`).\n\n## Quick Start\n\n1. **Install** — use npm or the install script:\n\n   ```bash\n   # npm (recommended)\n   npm install -g @scinddev/xcind\n\n   # Or use the install script\n   ./install.sh /usr/local\n   ```\n\n2. **Configure your project** — create a `.xcind.sh` file in your project root:\n\n   ```bash\n   # .xcind.sh\n   XCIND_ENV_FILES=(\".env\" \".env.local\")\n   XCIND_COMPOSE_DIR=\"docker\"\n   XCIND_COMPOSE_FILES=(\"compose.yaml\" \"compose.dev.yaml\")\n   ```\n\n3. **Use it** — from anywhere inside your project:\n\n   ```bash\n   xcind-compose up -d\n   xcind-compose build\n   xcind-compose exec php bash\n   xcind-compose ps\n   ```\n\n## How It Works\n\nWhen you run `xcind-compose`, it:\n\n1. Walks upward from `$PWD` to find the nearest `.xcind.sh` (the \"app root\")\n2. Sources `.xcind.sh` to load project-specific configuration\n3. For each file pattern in the config, expands shell variables and checks if\n   the file exists on disk\n4. For each existing file, also checks for an `.override` variant\n5. Assembles `--env-file` and `-f` flags and passes them to `docker compose`\n6. Forwards all your arguments to `docker compose`\n\n## Configuration Reference\n\nThe `.xcind.sh` file is a sourceable bash script. It may set the following variables:\n\n### `XCIND_ENV_FILES`\n\nArray of environment file patterns, relative to the app root. Each file that\nexists on disk is passed via `--env-file`. For each file, an `.override` variant\nis also checked (e.g., `.env` → `.env.override`).\n\n```bash\nXCIND_ENV_FILES=(\".env\" \".env.local\" '.env.${APP_ENV}')\n```\n\n### `XCIND_COMPOSE_DIR`\n\nOptional subdirectory where compose files live, relative to the app root.\nIf set, compose file patterns are resolved relative to this directory.\n\n```bash\nXCIND_COMPOSE_DIR=\"docker\"\n```\n\n### `XCIND_COMPOSE_FILES`\n\nArray of compose file patterns, relative to `XCIND_COMPOSE_DIR` (or the app root\nif `XCIND_COMPOSE_DIR` is unset). Each file that exists on disk is passed via `-f`.\nFor each file, an `.override` variant is also checked.\n\n```bash\nXCIND_COMPOSE_FILES=(\n    \"compose.common.yaml\"\n    'compose.${APP_ENV}.yaml'\n    \"compose.traefik.yaml\"\n)\n```\n\n### `XCIND_BAKE_FILES`\n\nArray of Docker Bake file patterns, relative to the app root. Reserved for future\nuse. Currently tracked in `xcind-config` JSON output but not passed to `docker compose`.\n\n```bash\nXCIND_BAKE_FILES=(\"docker-bake.hcl\")\n```\n\n## Override Resolution\n\nFor files with a recognized extension (`.yaml`, `.yml`, `.json`, `.hcl`, `.toml`),\nthe override variant inserts `.override` before the extension:\n\n| Base file                | Override variant                |\n| ------------------------ | ------------------------------- |\n| `compose.yaml`           | `compose.override.yaml`         |\n| `compose.common.yaml`    | `compose.common.override.yaml`  |\n| `docker-bake.hcl`        | `docker-bake.override.hcl`      |\n\nFor all other files (like env files), `.override` is appended:\n\n| Base file     | Override variant      |\n| ------------- | --------------------- |\n| `.env`        | `.env.override`       |\n| `.env.local`  | `.env.local.override` |\n\nFiles that don't exist on disk are silently skipped — both the base file and\nits override variant.\n\n## Variable Expansion\n\nFile patterns support shell variable expansion. Variables are expanded at\nruntime, so environment-specific files work naturally:\n\n```bash\nXCIND_COMPOSE_FILES=(\n    \"compose.common.yaml\"\n    'compose.${APP_ENV}.yaml'    # Note: single quotes to prevent premature expansion\n)\n```\n\nWith `APP_ENV=dev`, xcind checks for `compose.dev.yaml` and `compose.dev.override.yaml`.\nWith `APP_ENV=prod`, it checks for `compose.prod.yaml` and `compose.prod.override.yaml`.\n\n## Commands\n\n### `xcind-compose`\n\nThe main workhorse. Resolves config and passes everything through to `docker compose`.\n\n```bash\nxcind-compose up -d\nxcind-compose build --no-cache\nxcind-compose exec php bash\nxcind-compose down --remove-orphans\n```\n\n### `xcind-config`\n\nDumps the resolved configuration. Useful for debugging and for the JetBrains plugin.\n\n```bash\nxcind-config              # JSON output\nxcind-config --preview    # Show the docker compose command line\nxcind-config --files      # List resolved files\n```\n\n## Environment Variable Override\n\nSet `XCIND_APP_ROOT` to bypass automatic root detection:\n\n```bash\nXCIND_APP_ROOT=/path/to/project xcind-compose up\n```\n\n## Tab Completion\n\nSince `xcind-compose` passes everything through to `docker compose`, you can\nreuse Docker Compose's completion. Add to your shell config:\n\n```bash\n# If using the Docker CLI's built-in completion:\ncomplete -F _docker_compose xcind-compose 2\u003e/dev/null\n```\n\n## Direnv Integration\n\nXcind works independently of direnv. If you use direnv, you can optionally\nsource `.xcind.sh` from your `.envrc` to get the config variables in your shell:\n\n```bash\n# .envrc\nsource_env .xcind.sh\n```\n\n## JetBrains Plugin\n\nThe `xcind-config` command outputs JSON compatible with the xcind JetBrains\nplugin. Point the plugin at the `xcind-config` script path, and it will\nresolve compose files and env files for your IDE's Docker integration.\n\n## Installation\n\n### npm (recommended)\n\n```bash\n# Global install\nnpm install -g @scinddev/xcind\n\n# Or run directly with npx\nnpx -p @scinddev/xcind xcind-compose up -d\nnpx -p @scinddev/xcind xcind-config --preview\n```\n\n### Install script\n\n```bash\n# Install to /usr/local (may need sudo)\nsudo ./install.sh\n\n# Install to a custom prefix\n./install.sh ~/.local\n\n# Uninstall\nsudo ./uninstall.sh\n./uninstall.sh ~/.local\n```\n\n## Docker\n\nBuild and run the test suite in a container:\n\n```bash\ndocker compose build\ndocker compose run xcind\n```\n\nTest against a specific bash version:\n\n```bash\ndocker compose build --build-arg BASHVER=5.1\ndocker compose run xcind\n```\n\nFor an interactive shell, copy the override template:\n\n```bash\ncp compose.override.dist compose.override.yaml\ndocker compose run xcind\n```\n\n## File Structure\n\n```\nxcind/\n├── bin/\n│   ├── xcind-compose          # Main executable — wraps docker compose\n│   └── xcind-config           # Config dump — JSON, preview, file listing\n├── lib/xcind/\n│   └── xcind-lib.bash         # Shared library (sourced by other scripts)\n├── test/\n│   └── test-xcind.sh          # Test suite\n├── examples/\n│   ├── acmeapps/\n│   │   └── .xcind.sh          # Simple example\n│   └── advanced/\n│       └── .xcind.sh          # Variable expansion example\n├── install.sh                 # Install to a PREFIX\n├── uninstall.sh               # Remove from a PREFIX\n└── README.md\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscinddev%2Fxcind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscinddev%2Fxcind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscinddev%2Fxcind/lists"}