# colcon-clean
[](https://github.com/colcon/colcon-clean/actions/workflows/ci.yaml?query=branch%3Amaster+event%3Apush)
[](https://codecov.io/gh/colcon/colcon-clean)
An extension for [colcon-core](https://github.com/colcon/colcon-core) to clean package workspaces. Enables cleaning of various colcon paths, such as build or install folders, for either the entire workspace or for selected packages with advanced path globing options. In conjunction with [colcon-package-selection](https://github.com/colcon/colcon-package-selection), this extension can help maintain hygienic build environments while leveraging persistent workspaces for caching by allowing users to finely remove stale artifacts, preserving what can be cached during software development. For example, when pulling various changes into a local workspace to review pull requests, this extension can be used to wipe only the build and install paths for affected packages, ensuring subsequent builds are not cross contaminated from previous jobs.
The extension works by providing a convenient wrapper around filesystem deletion, allowing users to specify at which base paths to be cleaned (`build`, `install`, `log`, `test_result`), at what level cleaning should take place (global workspace or per package), and if specified what exact files should (or should not) be removed.
## Quick start
Setup, build and test an example colcon workspace:
```
mkdir -p ~/ws/src && cd ~/ws
wget https://raw.githubusercontent.com/colcon/colcon.readthedocs.org/main/colcon.repos
vcs import src < colcon.repos
colcon build
colcon test
```
Clean build and install paths for select packages:
```
colcon clean packages \
--base-select \
build \
install \
--packages-select \
colcon-cmake \
colcon-package-information
```
Clean gcov count data files for entire workspace:
```
colcon clean workspace \
--base-select \
build \
--clean-match \
"*.gcda"
```
## Subverbs
### `workspace` - Clean paths for workspace
The `workspace` subverb provides a means to globally clean the top level base paths for the entire workspace.
### `packages` - Clean paths for packages
The `packages` subverb provides a means to locally clean the package level base paths using package selection.
## Clean subverb arguments
By default, this extension will provide an interactive confirmation prompt with a printout of files to be deleted. This dialogue can be automatically skipped; these deletion events can still be observed via the command's resulting colcon log file.
- `-y`, `--yes`
- Automatic yes to prompts
### Base handler arguments
Additional arguments supported by all subverbs provide the option to select which base paths to clean, where they may be relocated:
- `--base-select`
- Select base names to clean in workspace (default: [build, install, log, test_result])
- `--base-ignore`
- Ignore base names to clean in workspace (default: [])
- `--build-base`
- The base path for all build directories (default: build)
- `--install-base`
- The base path for all install directories (default: install)
- `--log-base`
- The base path for all log directories (default: log)
- `--test-result-base`
- The base path for all test_result directories (default: build)
### Clean filter arguments
Specify what files and directories to include. All files and directories (including symbolic links) are included by default. The --clean-match/--clean-ignore arguments allows for selection using glob/wildcard (".gitignore style") path matching. Paths relative to the root `directory` (i.e. excluding the name of the root directory itself) are matched against the provided patterns. For example, to only include Gcov Data files, use: `colcon clean workspace --clean-match "*.gcda"` or to exclude hidden files and directories use: `colcon clean workspace --clean-ignore ".*" ".*/"` which is short for `colcon clean workspace --clean-match "*" "!.*" "!.*/"`.
- `--clean-match`
- One or several patterns for paths to include. NOTE: patterns with an asterisk must be in quotes ("*") or the asterisk preceded by an escape character (\*).
- `--clean-ignore`
- One or several patterns for paths to exclude. NOTE: patterns with an asterisk must be in quotes ("*") or the asterisk preceded by an escape character (\*).
- `--clean-no-linked-dirs`
- Do not include symbolic links to other directories.
- `--clean-no-linked-files`
- Do not include symbolic links to files.
## Extension points
This extension makes use of a number of colcon-core extension points for registering verbs, subverbs with colcon CLI. This extension also provides it's own extension points to support additional cleaning strategies.
### `BaseHandlerExtensionPoint`
This extension point determines the types of base paths that may be selected for cleaning. Default base handler extensions provided include:
- `build`
- Note: by default this extension does not follow symlinks
- `install`
- Note: by default this extension does not follow symlinks
- `log`
- Note: logs are stored by time, so package selection is not applicable
- `test_result`
- Note: by default colcon uses `build` path to store test results
Raw data
{
"_id": null,
"home_page": "https://colcon.readthedocs.io",
"name": "colcon-clean",
"maintainer": "Ruffin White",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "roxfoxpox@gmail.com",
"keywords": "colcon",
"author": "Ruffin White",
"author_email": "roxfoxpox@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/98/15/c169c9c971f12fc6a6a15e93b2a7740c162c085eac20048862814e00603d/colcon-clean-0.2.1.tar.gz",
"platform": null,
"description": "# colcon-clean\n\n[](https://github.com/colcon/colcon-clean/actions/workflows/ci.yaml?query=branch%3Amaster+event%3Apush)\n[](https://codecov.io/gh/colcon/colcon-clean)\n\nAn extension for [colcon-core](https://github.com/colcon/colcon-core) to clean package workspaces. Enables cleaning of various colcon paths, such as build or install folders, for either the entire workspace or for selected packages with advanced path globing options. In conjunction with [colcon-package-selection](https://github.com/colcon/colcon-package-selection), this extension can help maintain hygienic build environments while leveraging persistent workspaces for caching by allowing users to finely remove stale artifacts, preserving what can be cached during software development. For example, when pulling various changes into a local workspace to review pull requests, this extension can be used to wipe only the build and install paths for affected packages, ensuring subsequent builds are not cross contaminated from previous jobs.\n\nThe extension works by providing a convenient wrapper around filesystem deletion, allowing users to specify at which base paths to be cleaned (`build`, `install`, `log`, `test_result`), at what level cleaning should take place (global workspace or per package), and if specified what exact files should (or should not) be removed.\n\n\n## Quick start\n\nSetup, build and test an example colcon workspace:\n```\nmkdir -p ~/ws/src && cd ~/ws\nwget https://raw.githubusercontent.com/colcon/colcon.readthedocs.org/main/colcon.repos\nvcs import src < colcon.repos\ncolcon build\ncolcon test\n```\n\nClean build and install paths for select packages:\n```\ncolcon clean packages \\\n --base-select \\\n build \\\n install \\\n --packages-select \\\n colcon-cmake \\\n colcon-package-information\n```\n\nClean gcov count data files for entire workspace:\n```\ncolcon clean workspace \\\n --base-select \\\n build \\\n --clean-match \\\n \"*.gcda\"\n```\n\n\n## Subverbs\n\n### `workspace` - Clean paths for workspace\n\nThe `workspace` subverb provides a means to globally clean the top level base paths for the entire workspace.\n\n### `packages` - Clean paths for packages\n\nThe `packages` subverb provides a means to locally clean the package level base paths using package selection.\n\n\n## Clean subverb arguments\n\nBy default, this extension will provide an interactive confirmation prompt with a printout of files to be deleted. This dialogue can be automatically skipped; these deletion events can still be observed via the command's resulting colcon log file.\n\n- `-y`, `--yes`\n - Automatic yes to prompts\n\n### Base handler arguments\n\nAdditional arguments supported by all subverbs provide the option to select which base paths to clean, where they may be relocated:\n\n- `--base-select`\n - Select base names to clean in workspace (default: [build, install, log, test_result])\n- `--base-ignore`\n - Ignore base names to clean in workspace (default: [])\n- `--build-base`\n - The base path for all build directories (default: build)\n- `--install-base`\n - The base path for all install directories (default: install)\n- `--log-base`\n - The base path for all log directories (default: log)\n- `--test-result-base`\n - The base path for all test_result directories (default: build)\n\n### Clean filter arguments\n\nSpecify what files and directories to include. All files and directories (including symbolic links) are included by default. The --clean-match/--clean-ignore arguments allows for selection using glob/wildcard (\".gitignore style\") path matching. Paths relative to the root `directory` (i.e. excluding the name of the root directory itself) are matched against the provided patterns. For example, to only include Gcov Data files, use: `colcon clean workspace --clean-match \"*.gcda\"` or to exclude hidden files and directories use: `colcon clean workspace --clean-ignore \".*\" \".*/\"` which is short for `colcon clean workspace --clean-match \"*\" \"!.*\" \"!.*/\"`.\n\n- `--clean-match`\n - One or several patterns for paths to include. NOTE: patterns with an asterisk must be in quotes (\"*\") or the asterisk preceded by an escape character (\\*).\n- `--clean-ignore`\n - One or several patterns for paths to exclude. NOTE: patterns with an asterisk must be in quotes (\"*\") or the asterisk preceded by an escape character (\\*).\n- `--clean-no-linked-dirs`\n - Do not include symbolic links to other directories.\n- `--clean-no-linked-files`\n - Do not include symbolic links to files.\n\n\n## Extension points\n\nThis extension makes use of a number of colcon-core extension points for registering verbs, subverbs with colcon CLI. This extension also provides it's own extension points to support additional cleaning strategies.\n\n### `BaseHandlerExtensionPoint`\n\nThis extension point determines the types of base paths that may be selected for cleaning. Default base handler extensions provided include:\n\n- `build`\n - Note: by default this extension does not follow symlinks\n- `install`\n - Note: by default this extension does not follow symlinks\n- `log`\n - Note: logs are stored by time, so package selection is not applicable\n- `test_result`\n - Note: by default colcon uses `build` path to store test results\n\n\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "Extension for colcon to clean package workspaces.",
"version": "0.2.1",
"project_urls": {
"Changelog": "https://github.com/colcon/colcon-clean/milestones?direction=desc&sort=due_date&state=closed",
"GitHub": "https://github.com/colcon/colcon-clean/",
"Homepage": "https://colcon.readthedocs.io"
},
"split_keywords": [
"colcon"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3b460de3f2592e0d79630fe33d010fd7fcbd6fb2a371a764ece2d39a8b6432ff",
"md5": "c6b3ec6d9dcc882dac5e74965805e510",
"sha256": "f80cfa93835ab337c199b9872696065d9dd52068598a0bf2d2ac81a75f87dd3a"
},
"downloads": -1,
"filename": "colcon_clean-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c6b3ec6d9dcc882dac5e74965805e510",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 18968,
"upload_time": "2024-03-08T01:41:31",
"upload_time_iso_8601": "2024-03-08T01:41:31.905626Z",
"url": "https://files.pythonhosted.org/packages/3b/46/0de3f2592e0d79630fe33d010fd7fcbd6fb2a371a764ece2d39a8b6432ff/colcon_clean-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9815c169c9c971f12fc6a6a15e93b2a7740c162c085eac20048862814e00603d",
"md5": "e1dd8d2515ce7d0e172615aa9b7eb985",
"sha256": "f2bbf2724db84b122184ff402a247b8758d8f692c9f32ba53801f69da6dceb54"
},
"downloads": -1,
"filename": "colcon-clean-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "e1dd8d2515ce7d0e172615aa9b7eb985",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 18612,
"upload_time": "2024-03-08T01:41:33",
"upload_time_iso_8601": "2024-03-08T01:41:33.595284Z",
"url": "https://files.pythonhosted.org/packages/98/15/c169c9c971f12fc6a6a15e93b2a7740c162c085eac20048862814e00603d/colcon-clean-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-08 01:41:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "colcon",
"github_project": "colcon-clean",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "colcon-clean"
}
JSON
