{"id":15458135,"url":"https://github.com/dmotz/distilla","last_synced_at":"2025-06-27T10:06:57.254Z","repository":{"id":141713101,"uuid":"85435737","full_name":"dmotz/distilla","owner":"dmotz","description":"Distill a derived branch build with no mess. Designed for gh-pages.","archived":false,"fork":false,"pushed_at":"2020-01-25T17:31:18.000Z","size":15,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-27T10:05:37.563Z","etag":null,"topics":["cli","gh-pages","github-pages","javascript","static"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/dmotz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2017-03-18T22:21:06.000Z","updated_at":"2021-01-21T18:36:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"2c799871-5dde-4d53-8db3-be275f093ea4","html_url":"https://github.com/dmotz/distilla","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dmotz/distilla","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmotz%2Fdistilla","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmotz%2Fdistilla/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmotz%2Fdistilla/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmotz%2Fdistilla/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dmotz","download_url":"https://codeload.github.com/dmotz/distilla/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmotz%2Fdistilla/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262235779,"owners_count":23279566,"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":["cli","gh-pages","github-pages","javascript","static"],"created_at":"2024-10-01T22:59:33.483Z","updated_at":"2025-06-27T10:06:57.227Z","avatar_url":"https://github.com/dmotz.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Distilla ⚗️\n#### Distill a derived branch build with no mess. Designed for `gh-pages`.\n---\n\nDistilla is a simple command-line tool for automatically updating and pushing a\nGit branch derived from another. The target use case is deploying a GitHub Pages\n(`gh-pages`) branch based on a master branch using a simple config file.\n\nRunning `distilla` on your working branch will run build tasks behind the scenes\nto generate artifacts then commit and push them to your target branch without\ntouching your working tree.\n\nThe current alternative is often tedious and messy:\n\n- After making a change to your master branch, you run build tasks (e.g.\n  creating JS and CSS bundles) which clutter your working directory with\n  derived artifacts you don't want to commit to master.\n\n- You typically then have to move these files to a temporary directory so you\n  can switch to your `gh-pages` branch. If you have other pending changes on\n  master, you'll have to take the time `git stash` them before you can move along.\n\n- Once on the `gh-pages` branch you have to manually move the bundles to their\n  destinations, test it out, commit, and push.\n\n- You can then return to master and apply your stash to continue where you left\n  off.\n\nSurely we can automate this (and without touching the current working branch)...\n\nNow with Distilla:\n\n- Create a `.distilla` config file in your master branch's root with a list of\n  build tasks.\n\n- Run `distilla`. The derived branch is built, committed, and pushed automatically\n  without the need to stash changes.\n\n\nBehind the scenes Distilla creates temporary copies of your repo and performs\nsome surgery to commit the desired output without manual tedium.\n\n\n## Install\n\n```\n$ npm install -g distilla\n```\n\n## Configure\n\nBy default Distilla config files are YAML files holding a list of tasks:\n\n```yaml\ntasks:\n  npm run bundle:\n    - bundle.js\n    - js/main.js\n\n  stylus -u nib -c main.styl:\n    - main.css\n    - css/main.css\n```\n\nIf you don't like YAML you can also write your config files as JSON:\n\n```json\n{\n  \"tasks\": {\n    \"npm run bundle\": [\n      \"bundle.js\",\n      \"js/main.js\"\n    ],\n    \"stylus -u nib -c main.styl\": [\n      \"main.css\",\n      \"css/main.css\"\n    ]\n  }\n}\n```\n\nUnder `tasks`, each map key is a build command to run. The value for each key is\npairing of a source (where the build script outputs the file) and a destination\n(where you want to put that output on your derived branch).\n\nYou can simplify this further by cutting out the intermediate trip to disk. If\nyour script outputs to `stdout` instead of writing to a file, specify only a\ndestination in the task:\n\n```yaml\ntasks:\n  npm run bundle: js/main.js\n```\n\nThis keeps your task configuration even cleaner reducing the noise of temporary paths.\n\nAs a further example, if you wanted to simply move a file unmodified to your\nderived branch, you would write this:\n\n```yaml\ntasks:\n  cat robots.txt: robots.txt\n```\n\nWhen you run `distilla` the tasks' outputs will be put in place on the derived\nbranch and pushed.\n\n\n## Preview changes\n\nBy setting `preview: true` in your config, Distilla will offer to show you a\nworking version of the changes in a browser before you push:\n\n```yaml\npreview: true\n\ntasks:\n  # ...\n```\n\nDistilla will run a server for testing out changes and if things look hunky-dory,\nit will continue with pushing.\n\n\n## Other options\n\nBy default Distilla will commit with a message that includes the source branch\nand commit, e.g.:\n\n```\nupdated build from master d63374ab730e24ea9021426a91d45fdb0b8b71d0\n```\n\nYou can customize this message in your config file using the tokens `%h`, `%b`,\nand `%m`, which will be replaced with the last commit hash, source branch, and\nlast commit message respectively.\n\n```yaml\npreview: true\n\ncommit-msg: rebuild based on %m\n\ntasks:\n  # ...\n```\n\nYou can also override the remote default (`origin`):\n\n```yaml\nremote: xanadu\n```\n\n...and the target branch (default `gh-pages`):\n\n```yaml\ntarget: website\n```\n\n\n## Asset hashing\n\nOne final normally tedious task Distilla can assist with is adding hash suffixes\nto hash URLs to break caching after updates.\n\nGitHub Pages employs powerful caching mechanisms (a good thing), but sometimes\nthe grip is held too tightly when we make amendments.\n\nIn the `.distilla` config file, you can a `hashing` task where the keys are\npaths to html files and the values are lists of asset paths to update:\n\n```yaml\nhashing:\n  index.html:\n    - js/bundle.js\n    - css/main.css\n```\n\nDistilla will update the markup with the hashes appended to the query string:\n```html\n\u003cscript src=\"js/bundle.js?17df15065bd4854c38debe54fd33d099fdf38ed5\"\u003e\u003c/script\u003e\n\u003clink href=\"css/main.css?de67d412baa5bbcb854f067a6d49e3cbf396cbd5\" rel=\"stylesheet\" type=\"text/css\"\u003e\n```\n\n\n## Caveats\n\nRemember, Distilla is in alpha state and will automatically push commits to your\ntarget branch  (`gh-pages` by default) so be sure to thoroughly test\n(using `preview: true`) before running.\n\nIf you're using the `stdout` of npm scripts as tasks, be sure to use the `silent`\nflag to prevent diagnostic output from being prepended to your build files\n(`npm run -s bundle`).\n\n\n## *distilla*?\nDistillation, distribution, J Dilla.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmotz%2Fdistilla","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdmotz%2Fdistilla","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmotz%2Fdistilla/lists"}