# gpm dist-tag Manage distribution tags for packages. ## Usage ```bash gpm dist-tag [command] ``` ## Commands | Command | Description | Usage | | --------------------------------------------- | ------------------------- | -------------------------------------------- | | [`gpm dist-tag add`](#gpm-dist-tag-add) | Add a distribution tag | `gpm dist-tag add ` | | [`gpm dist-tag list`](#gpm-dist-tag-list) | List distribution tags | `gpm dist-tag list ` | | [`gpm dist-tag remove`](#gpm-dist-tag-remove) | Remove a distribution tag | `gpm dist-tag remove ` | ## Description The `gpm dist-tag` command manages distribution tags for packages. Distribution tags are aliases for package versions that make it easier to reference specific versions or release channels. ### Common Distribution Tags * **latest**: Default tag for the most recent stable version * **beta**: Beta release channel * **alpha**: Alpha release channel * **stable**: Stable release channel * **next**: Next major version preview ## gpm dist-tag add Add a distribution tag to a package version. ### Usage ```bash gpm dist-tag add ``` ### Arguments * `` - Package name (e.g., `com.company.package`) * `` - Distribution tag name (e.g., `beta`, `stable`) * `` - Package version to tag (e.g., `1.0.0`, `2.0.0-beta.1`) ### Examples ```bash # Add beta tag to version gpm dist-tag add com.company.package beta 1.0.0-beta.1 # Add stable tag to version gpm dist-tag add com.company.package stable 1.0.0 # Add latest tag to version gpm dist-tag add com.company.package latest 1.0.0 ``` ### Output ``` Distribution Tag Added ───────────────────── Package: com.company.package Tag: beta Version: 1.0.0-beta.1 ───────────────────── Tag 'beta' added to com.company.package@1.0.0-beta.1 ``` ## gpm dist-tag list List distribution tags for a package. ### Usage ```bash gpm dist-tag list ``` ### Arguments * `` - Package name (e.g., `com.company.package`) ### Examples ```bash # List all tags for package gpm dist-tag list com.company.package # List tags with JSON output gpm dist-tag list com.company.package --json ``` ### Output ``` Distribution Tags ───────────────────────────────────────── Package: com.company.package ───────────────────────────────────────── latest: 1.0.0 beta: 1.0.0-beta.1 alpha: 1.0.0-alpha.1 stable: 1.0.0 ───────────────────────────────────────── 4 tags found ``` ### JSON Output ```json { "success": true, "package": "com.company.package", "tags": { "latest": "1.0.0", "beta": "1.0.0-beta.1", "alpha": "1.0.0-alpha.1", "stable": "1.0.0" }, "count": 4, "message": "4 tags found" } ``` ## gpm dist-tag remove Remove a distribution tag from a package. ### Usage ```bash gpm dist-tag remove ``` ### Arguments * `` - Package name (e.g., `com.company.package`) * `` - Distribution tag to remove (e.g., `beta`, `alpha`) ### Examples ```bash # Remove beta tag gpm dist-tag remove com.company.package beta # Remove alpha tag gpm dist-tag remove com.company.package alpha ``` ### Output ``` Distribution Tag Removed ─────────────────────── Package: com.company.package Tag: beta ─────────────────────── Tag 'beta' removed from com.company.package ``` ## Common Workflows ### Release Management ```bash # 1. Publish new version gpm publish --access=scoped # 2. Add beta tag gpm dist-tag add com.company.package beta 1.0.0-beta.1 # 3. Test beta version gpm install com.company.package@beta # 4. Promote to stable gpm dist-tag add com.company.package stable 1.0.0 gpm dist-tag add com.company.package latest 1.0.0 ``` ### Version Channels ```bash # Set up release channels gpm dist-tag add com.company.package alpha 1.0.0-alpha.1 gpm dist-tag add com.company.package beta 1.0.0-beta.1 gpm dist-tag add com.company.package stable 1.0.0 # List all channels gpm dist-tag list com.company.package ``` ### Tag Management ```bash # List current tags gpm dist-tag list com.company.package # Remove old tags gpm dist-tag remove com.company.package old-tag # Add new tags gpm dist-tag add com.company.package new-tag 1.0.0 ``` ## Tag Naming Conventions ### Recommended Tags * **latest**: Most recent stable version * **stable**: Stable release channel * **beta**: Beta release channel * **alpha**: Alpha release channel * **next**: Next major version preview * **v1**: Major version 1.x * **v2**: Major version 2.x ### Tag Best Practices ```bash # Use semantic tag names gpm dist-tag add com.company.package stable 1.0.0 gpm dist-tag add com.company.package beta 1.1.0-beta.1 # Avoid confusing tags gpm dist-tag add com.company.package release 1.0.0 # Good gpm dist-tag add com.company.package v1 1.0.0 # Good gpm dist-tag add com.company.package temp 1.0.0 # Avoid ``` ## Error Handling ### Common Errors * **Package not found**: `Package 'com.company.package' not found` * **Tag already exists**: `Tag 'beta' already exists for package` * **Version not found**: `Version '1.0.0' not found for package` * **Authentication required**: `Authentication required for this operation` ### Troubleshooting 1. **Package not found**: Verify package name and registry 2. **Tag already exists**: Remove existing tag first or use different tag name 3. **Version not found**: Check available versions with `gpm info ` 4. **Authentication required**: Run `gpm login` to authenticate ## Integration with Publishing ### Publish with Tags ```bash # Publish with specific tag gpm publish --tag=beta # Publish and add additional tags gpm publish --tag=latest gpm dist-tag add com.company.package stable 1.0.0 ``` ### Tag Management in CI/CD ```bash # Add tags in CI gpm dist-tag add com.company.package ci-build $BUILD_NUMBER # Remove old tags gpm dist-tag remove com.company.package old-ci-build ``` ## Related Commands * [`gpm publish`](/cli-reference/cli/publishing/publish.md) - Publish package to registry * [`gpm info`](/cli-reference/cli/registry/info.md) - Show package information * [`gpm search`](/cli-reference/cli/registry/search.md) - Search for packages ## See Also * [Publishing Overview](/cli-reference/cli/publishing.md) * [Package Versioning](https://github.com/gpm-sh/docs/blob/main/packages/versioning.md) * [Registry Operations](/cli-reference/cli/registry.md) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.gpm.sh/cli-reference/cli/publishing/dist-tag.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.