{"id":23219633,"url":"https://github.com/barcek/compost","last_synced_at":"2026-05-11T03:01:50.503Z","repository":{"id":182041667,"uuid":"666071963","full_name":"barcek/compost","owner":"barcek","description":"recycling containers | command store \u0026 argument finesser | command-line tool | Python + Mypy, w/ SQLite","archived":false,"fork":false,"pushed_at":"2025-01-03T12:45:26.000Z","size":60,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-11T11:53:01.738Z","etag":null,"topics":["command-line-tool","devops","docker","dx","object-oriented-programming","python","sql","sqlite"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/barcek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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}},"created_at":"2023-07-13T16:37:00.000Z","updated_at":"2025-01-14T12:54:06.000Z","dependencies_parsed_at":null,"dependency_job_id":"698dc960-63f2-4b8c-8510-69bea154d2be","html_url":"https://github.com/barcek/compost","commit_stats":null,"previous_names":["barcek/compost"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barcek%2Fcompost","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barcek%2Fcompost/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barcek%2Fcompost/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barcek%2Fcompost/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/barcek","download_url":"https://codeload.github.com/barcek/compost/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247353742,"owners_count":20925329,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["command-line-tool","devops","docker","dx","object-oriented-programming","python","sql","sqlite"],"created_at":"2024-12-18T21:36:11.772Z","updated_at":"2026-05-11T03:01:50.440Z","avatar_url":"https://github.com/barcek.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# compost\n\nRecycle Docker commands.\n\nA CLI tool for command storage, rerun and modification, with type annotation and a self-test.\n\n## Why?\n\nFor the flexibility of single containers with more of the preset approach offered by Compose.\n\nUseful for learning what Docker can do without the initial overhead of remembering specific commands, and, once comfortable, as a tool for iterating towards a preferred container set.\n\n## How?\n\nPrefacing a supported Docker command with `compost` (see [Getting started](#getting-started) below) stores the command, prints an ID to the terminal for later reference then runs the command as usual. For example, for `docker run`:\n\n```shell\ncompost docker run \u003cremaining_args\u003e\n```\n\nThis prints the storage ID, specifically '1' if the command run was the very first. This ID allows the Docker command to be rerun using `compost` and the Docker keyword only, i.e. avoiding the need to locate the previously run command in history or recreate the set of arguments.\n\nFor example, if the command was a `Docker run` command and the ID was in fact '1':\n\n```shell\ncompost run 1\n```\n\n### Rerunning with changes\n\nA stored command can be rerun with one or more of its arguments changed, by passing after the ID only the arguments to be updated.\n\n```shell\ncompost run \u003cID\u003e \u003cargs_for_update\u003e\n```\n\nThis retains the original command in storage, with the same ID, but stores the modified version under its own new ID, printing the new ID then running the modified command.\n\nPositional arguments passed in this way are replaced, as are options taking their own arguments, while boolean options are toggled. For example, take this initial command:\n\n```shell\ncompost docker run -de TEST=test test:1.0.0\n```\n\nIf the ID printed were '1', the command could be rerun with the 'detach' option unset and the image string updated as follows:\n\n```shell\ncompost run 1 -d test:1.0.1\n```\n\nThis would store, print the ID for and run the following modified command:\n\n```shell\ncompost docker run --env TEST=test test:1.0.1\n```\n\nFor commands with more than one positional argument, when changing the second or later positional argument any preceding positional arguments should be passed too. As above, multipart positional arguments such as commands should be passed as a single string.\n\nOptions are available allowing the command to be printed and/or deferred (see [Options](#options) below).\n\n### Storage of commands\n\nThe commands are stored in an SQLite database created by default in the '/home' directory for the user, per the `$HOME` environment variable, with the default filename '.compost.db'. For testing, a temporary database is created in the same directory with the default filename '.compost_test.db'.\n\nThe full paths and table creation strings are set close to the top of the source file.\n\n### Supported arguments\n\nCurrently supported are the keywords `run` and `exec` with positional arguments and a subset of the options offering a short flag, plus `--name` and `--rm`. Any multipart positional argument, such as a command with its own arguments, should be passed quoted.\n\nThe flags available and action performed for each by `ArgumentParser` are defined close to the top of the source file.\n\n### Listing and deletion\n\nA command can be deleted from the store by including the argument `rm`:\n\n```shell\ncompost \u003ckeyword\u003e rm \u003cID\u003e\n```\n\nAll commands stored can be listed by including `ls`:\n\n```shell\ncompost \u003ckeyword\u003e ls\n```\n\nUsage can be seen with `compost help`, or with the `--help` or `-h` flag.\n\n## Options\n\nThe following can be passed to `compost` either a) before a Docker command or b) after the `exec` or `run` keyword when rerunning with or without changes:\n\n- `--defer` / `-d`, to store the command without running\n- `--print` / `-p`, to show the command stored\n- `--help` / `-h`, to show help text then exit\n- `--version` / `-v`, to show name and version number then exit\n- `--test` / `-t`, to perform the self-test then exit\n\n## Getting started\n\nThe source file is written in Python 3.11 using the standard library only, with type annotation.\n\nOn a Linux system with a compatible version of Python installed, the source file can be run with the command `python3 compost` while in the same directory, and from elsewhere using the pattern `python3 path/to/compost`.\n\nAlternatively, it can be run with only `./compost` / `path/to/compost`, by first making it executable, if not already, with `chmod +x compost`. Once executable, it can be run from any directory with the simpler `compost` by placing it in a directory listed on the `$PATH` environment variable, e.g. '/bin' or '/usr/bin'.\n\nThe hashbang at the top of the file assumes the presence of Python 3.11 in '/usr/bin', the source code that Docker itself is installed and can be invoked directly with `docker`.\n\n## Code verification\n\nThe test cases can be run with `compost` followed by `test`, `--test` or `-t` (see [Getting started](#getting-started) and [Options](#options) above). The type annotation can be checked with Mypy, e.g. using the command `mypy --python-version 3.11 compost`.\n\n## Development plan\n\n- extend rerun, listing and removal to accept multiple IDs\n- allow for ID reuse\n- implement command name provision and reference\n- allow for independent positional argument and argument part update\n- include outstanding options to the Docker commands currently supported\n- support additional Docker commands\n- extend the database schema for context and provide keywords for inspection and analysis\n- generalize the classes to allow for use with other tools and extend to package format\n- improve error handling\n- extend testing\n- add comments\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarcek%2Fcompost","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbarcek%2Fcompost","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarcek%2Fcompost/lists"}