{"id":16300568,"url":"https://github.com/melezhik/tomtit","last_synced_at":"2025-08-21T10:15:43.593Z","repository":{"id":44613349,"uuid":"184820794","full_name":"melezhik/Tomtit","owner":"melezhik","description":"Tomtit - Raku Task Runner","archived":false,"fork":false,"pushed_at":"2025-02-14T11:52:18.000Z","size":411,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-17T15:08:08.101Z","etag":null,"topics":["bash","raku","sparrow6","task-runner"],"latest_commit_sha":null,"homepage":"","language":"Raku","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/melezhik.png","metadata":{"files":{"readme":"README.md","changelog":"Changes","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}},"created_at":"2019-05-03T21:11:43.000Z","updated_at":"2025-02-14T11:52:22.000Z","dependencies_parsed_at":"2024-01-04T09:50:29.558Z","dependency_job_id":"64d57877-1c0d-4751-86d4-03693a668a39","html_url":"https://github.com/melezhik/Tomtit","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/melezhik%2FTomtit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/melezhik%2FTomtit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/melezhik%2FTomtit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/melezhik%2FTomtit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/melezhik","download_url":"https://codeload.github.com/melezhik/Tomtit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244559873,"owners_count":20472211,"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":["bash","raku","sparrow6","task-runner"],"created_at":"2024-10-10T20:51:38.908Z","updated_at":"2025-08-21T10:15:43.579Z","avatar_url":"https://github.com/melezhik.png","language":"Raku","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tomtit\n\nTomtit - Raku Task Runner\n\n# Build Status\n\n![SparkyCI](https://sparky.sparrowhub.io/badge/gh-melezhik-Tomtit?foo=bar)\n\n# Install\n\n```bash\nzef install Tomtit\n```\n\n# Quick start\n\nTomtit is a task runner based on Sparrow6 engine, so just drop a few tasks under _some_ folder\nand run them as Raku scenarios:\n\n```bash\nmkdir -p tasks/hello\n```\n\n`tasks/hello/task.bash`:\n\n```bash\necho \"hello world\"\n```\n\n`.tom/hello.raku`:\n\n```raku\ntask-run \"tasks/hello\";\n```\n\nYou can do _more_ then that, [read more](https://github.com/melezhik/Sparrow6/blob/master/documentation/development.md) \nabout Sparrow6 tasks on Sparrow6 documentation.\n\n# Cli api\n\n    tom $action|$options $thing\n\nInitialize tomtit:\n\n\ttom --init\n\nRun scenario:\n\n    tom $scenario\n\nDefault action (list of scenarios):\n\n    tom\n\nList available scenarios:\n\n    tom --list\n\nGet help:\n\n    tom --help\n\nShow the last executed scenario:\n\n    tom --last\n\nClean Tomtit cache:\n\n    tom --clean\n\nExample:\n\n    tom --list\n\n    [scenarios list]\n    test\n    build\n    install\n\n    tom test        \n\n# Create scenarios\n\nTomtit scenarios are just Raku wrappers for underlying Sparrow6 tasks. \n\nCreate a `.tom` directory, to hold all the scenarios:\n\n    mkdir .tom/\n    nano .tom/build.raku\n    nano .tom/test.raku\n    nano .tom/install.raku\n\nAnd the drop some tasks at _some_ folder:\n\n`tasks/build/task.bash`:\n\n```bash\nset -e\nmake\nmake test\nsudo make install \n```\n\n`.tom/build.raku`:\n\n```raku\ntask-run \"tasks/build\";\n```\n\nNote above that the primary task in the folder has the filename `task.bash`.\nIn your scenario file, the `task-run` command will only take a directory, but \nit will be looking for a file with the name `task.*` (where * can be any of \nthe supported languages).  The advantage is that eg. task.bash can be changed \nto task.raku (or any other switch) without affecting the code that calls the \ntask, since parameters are passed to tasks the same way regardless of \nunderlying language.  \n\nIt's also possible to pass parameters to `task-run`, as per the \n[Task Configuration](https://github.com/melezhik/Sparrow6/blob/master/documentation/development.md#task-configuration)\ndocumentation; these override the configuration for the task.  \n\nIn order to avoid committing the Tomtit cache to your Source Control \nManagement, you may wish to add it to your .gitignore:\n\n    git add .tom/\n    echo .tom/.cache \u003e\u003e .gitignore\n\n# Using pre built Sparrow6 DSL functions\n\n[Sparrow6 DSL](https://github.com/melezhik/Sparrow6/blob/master/documentation/dsl.md) provides\none with ready to use function for some standard automation tasks:\n\n\n`.tom/example.raku`:\n\n```raku\n\n# you can use Sparrow6 DSL functions\n# to do many system tasks, like:\n\n# creation of files and directories\n\nfile 'passwords.txt', %( \n    owner =\u003e \"root\",\n    mode =\u003e \"700\",    \n    content =\u003e \"super secret\" \n);\n\ndirectory '.cache', %(\n    owner =\u003e \"server\"\n);\n\n# or restarting of services\n\nservice-restart \"web-app\";\n\n# or you can run a specific sparrow plugin\n# by using task-run function:\n\ntask-run 'my task', 'plugin', %( foo =\u003e 'bar' );\n\n# for example, to set git repository, \n# use git-base plugin:\n\ntask-run \"set git\", \"git-base\", %(\n    email =\u003e 'melezhik@gmail.com',\n    name  =\u003e 'Alexey Melezhik',\n    config_scope =\u003e 'local',\n    set_credential_cache =\u003e 'on'\n);\n```\n\n# Profiles\n\nProfiles are predefined sets of Tomtit scenarios.\nTo start using scenarios from profile you say:\n\n    tom --profile $profile\n\nOnce the command is executed the profile scenarios get installed to the\nbase Tomtit directory.\n\nTo list available profiles say this:\n\n    tom --profile\n\nTo list profiles scenarios say this:\n\n    tom --list --profile $profile\n\nYou can install selected scenario from profile by using special notation:\n\n    tom --profile $profile@$scenario\n\nFor example to install `commit` scenario from `git` profile:\n\n    tom --profile git@commit \n\n# Portable profiles\n\nTomtit exposes API to create portable profiles as regular Raku modules.\n\nYou should create Raku module in `Tomtit::Profile` namespace with the _our_ function `profile-data`, \nreturning `Hash` with scenarios data.\n\nFor example:\n\n```raku\nunit module Tomtit::Profile::Pets:ver\u003c0.0.1\u003e;\n\nour sub profile-data () {\n\n    my %a is Map  = (\n        cat   =\u003e (slurp %?RESOURCES\u003ccat.raku\u003e.Str),\n        dog   =\u003e (slurp %?RESOURCES\u003cdog.raku\u003e.Str),\n        fish  =\u003e (slurp %?RESOURCES\u003cfish.raku\u003e.Str)\n    );\n\n}\n```\n\nThe above module defines [Tomtit::Profile::Pets](https://github.com/melezhik/tomtit-profile-pets) profile with 3 scenarios `cat, dog, fish` installed as module resources:\n\n    resources/\n      cat.raku\n      dog.raku\n      fish.raku\n\n\nNow we can install it as regular Raku module and use through tom:\n\n    zef install Tomtit::Profile::Pets\n\nOnce module is installed we can install related profile. Note that we should replace `::` by `-` (\\*) symbols\nwhen referring to profile name.\n\n    tom --list --profile Tomtit-Profile-Pets\n\n    load portable profile Tomtit::Profile::Pets as Raku module ...\n    [profile scenarios]\n    Tomtit::Profile::Pets@cat       installed: False\n    Tomtit::Profile::Pets@dog       installed: False\n    Tomtit::Profile::Pets@fish      installed: False\n\n    tom --profile Tomtit-Profile-Pets\n\n    install Tomtit::Profile::Pets@cat ...\n    install Tomtit::Profile::Pets@dog ...\n    install Tomtit::Profile::Pets@fish ...\n\n(\\*) Tomtit require such a mapping so that Bash completion could work correctly.\n\n# Removing scenarios\n\nTo remove installed scenario say this:\n\n    tom --remove $scenario\n\n# Edit scenario source code\n\nUse `--edit` to create scenario from the scratch or to edit existed scenario source code:\n\n    tom --edit $scenario\n\n# Getting scenario source code\n\nUse `--cat` command to print out scenario source code:\n\n    tom --cat $scenario\n\nUse `--lines` flag to print out with line numbers.\n\n# Environments\n\nThe purpose of environments is that you can separately configure production, \ndevelopment, testing, and any other environemnts you choose.  This gives you\nthe ability to easily vary configuration on a per-environment basis.  \n\n* Tomtit environments are configuration files, written on Raku and technically speaking are plain Raku Hashes\n\n* Environment configuration files should be placed at `.tom/conf` directory:\n\n.tom/env/config.raku:\n\n\n    {\n        name =\u003e \"Tomtit\",\n        who-are-you =\u003e \"smart bird\"\n\n    }\n\nRun Tomtit.\n\nIt will pick the `.tom/env/config.raku` and read configuration from it, variables will be accessible as `config` Hash,\ninside Tomtit scenarios:\n\n\n    my $name = config\u003cname\u003e;\n    my $who-are-you = config\u003cwho-are-you\u003e;\n\n\nTo define _named_ configuration ( environment ), simply create `.tom/env/config{$env}.raku` file and refer to it through \n`--env=$env` parameter:\n\n    nano .tom/env/config.prod.raku\n\n    tom --env=prod ... other parameters here # will run with production configuration\n\nYou can run editor for environment configuration by using --edit option:\n\n    tom --env-edit test    # edit test enviroment configuration\n\n    tom --env-edit default # edit default configuration\n\nYou can activate environment by using `--env-set` parameter:\n\n    tom --env-set prod    # set prod environment as default\n    tom --env-set         # to list active (current) environment\n    tom --env-set default # to set current environment to default\n\nTo view environment configuration use `--env-cat` command:\n\n    tom --env-cat $env\n\nYou print out the list of all environments by using `--env-list` parameters:\n\n    tom --env-list\n\n## Common environments\n\nIt's handy to have so called common environments that get mixed into any environment\nadding some common configuration data. Just create `any` environemnt and that's will be it:\n\n```bash\ntom --edit any\n```\n\n```raku\n#!raku\n%(\n  foo =\u003e \"bar\",\n  id =\u003e 1000,\n)\n```\n\n```bash\ntom --edit my\n```\n\n```raku\n#!raku\n%(\n  # override some default\n  # parameters\n  # defined in any\n  foo =\u003e \"bar1\",\n  name =\u003e \"John\",\n)\n```\n\n```\ntom --edit dump-conf\n```\n\n```raku\nsay config().raku;\n```\n\n```\ntom --env=my dump-conf\n```\n\n```\nload configuration from /Users/alex/projects/Tomtit/.tom/env/config.my.raku\nmix in common configuration from /Users/alex/projects/Tomtit/.tom/env/config.any.raku\n14:11:47 :: [repository] - index updated from https://sparrowhub.io/repo/api/v1/index\n{:foo(\"bar1\"), :id(1000), :name(\"John\")}\n```\n\n# Tomtit cli configuration\n\nYou can set Tomtit configuration in `~/tom.yaml` file:\n\n    # list of portable Tomtit profiles,\n    # will be available through Bash completion\n\n    profiles:\n\n      - Tomtit-Foo\n      - Tomtit-Bar\n      - Tomtit-Bar-Baz\n\n    # you can also setup some Tomtit cli options here\n\n    options:\n\n      quiet: true\n\n# Options\n\n    --verbose          # run scenario in verbose mode\n    --quiet,-q         # run scenario in less verbose mode\n    --color            # color output\n    --no_index_update  # don't update Sparrow repository index\n    --dump_task        # dump task code before execution, see SP6_DUMP_TASK_CODE Sparrow documentation\n\nExample of `~/tom.yaml` file:\n\n```yaml\noptions:\n  no_index_update: true\n  quiet: true\n```\n\n# Bash completion\n\nYou can install Bash completion for tom cli.\n\n    tom --completion\n    source  ~/.tom_completion.sh\n\n# Development\n\n    git clone https://github.com/melezhik/Tomtit.git\n    zef install --/test .\n    zef install Tomtit\n    tom\n\n# See also\n\n* [ake](https://github.com/Raku/ake) - a Raku make-a-like inspired by rake\n\n# Author\n\nAlexey Melezhik\n\n# Thanks to\n\nGod Who gives me inspiration in my work\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmelezhik%2Ftomtit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmelezhik%2Ftomtit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmelezhik%2Ftomtit/lists"}