{"id":13649065,"url":"https://github.com/mattly/bork","last_synced_at":"2025-09-27T15:32:00.430Z","repository":{"id":9107779,"uuid":"10889040","full_name":"mattly/bork","owner":"mattly","description":"the Bash-Operated Reconciling Kludge","archived":true,"fork":false,"pushed_at":"2021-02-13T22:41:21.000Z","size":382,"stargazers_count":217,"open_issues_count":21,"forks_count":27,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-01-12T02:11:36.789Z","etag":null,"topics":["bash","configuration","shell","unix-utilities"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mattly.png","metadata":{"files":{"readme":"Readme.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-06-23T17:46:26.000Z","updated_at":"2025-01-02T17:56:06.000Z","dependencies_parsed_at":"2022-08-29T03:01:45.014Z","dependency_job_id":null,"html_url":"https://github.com/mattly/bork","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattly%2Fbork","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattly%2Fbork/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattly%2Fbork/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattly%2Fbork/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mattly","download_url":"https://codeload.github.com/mattly/bork/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234448352,"owners_count":18834213,"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","configuration","shell","unix-utilities"],"created_at":"2024-08-02T01:04:44.734Z","updated_at":"2025-09-27T15:32:00.156Z","avatar_url":"https://github.com/mattly.png","language":"Shell","funding_links":[],"categories":["Shell","Archive/abandoned projects"],"sub_categories":["macOS"],"readme":"# Bork - (no longer under development)\n\nBork puts the 'sh' back into IT. [Bork Bork Bork](https://www.youtube.com/results?search_query=swedish+chef).\n\nBork is no longer under active development. If you fork it and your fork gets some steam going, please let me know, I'm happy to add you to this list.\n\n## Known Active Forks:\n\n- [Skylar MacDonald](https://github.com/skylarmacdonald/bork)\n\n## the Swedish Chef Puppet of Config Management\n\nBork is a bash DSL for making declarative assertions about the state of a system.\n\nBork is written against Bash 3.2 and common unix utilities such as sed, awk and\ngrep. It is designed to work on any UNIX-based system and maintain awareness of\nplatform differences between BSD and GPL versions of unix utilities.\n\n# Installation\n\n## From source\n\n1. Clone this repository:\n  `git clone https://github.com/mattly/bork /usr/local/src/bork`\n\n1. Symlink the bork binaries into your `$PATH`:\n```bash\n  ln -sf /usr/local/src/bork/bin/bork /usr/local/bin/bork\n```\n\n## via Homebrew (Mac OS X)\n\n1. Install via Homebrew:\n  `brew install bork`\n\n# Usage and Operations\n\nRunning bork without arguments will output some help:\n\n```\nbork usage:\n\nbork operation [config-file] [options]\n\nwhere \"operation\" is one of:\n\n- check:      perform 'status' for a single command\n    example:  bork check ok github mattly/dotfiles\n- compile:    compile the config file to a self-contained script output to STDOUT\n    --conflicts=(y|yes|n|no)  If given, sets an automatic answer for conflict resolution.\n    example:  bork compile dotfiles.sh --conflicts=y \u003e install.sh\n- do:         perform 'satisfy' for a single command\n    example:  bork do ok github mattly/dotfiles\n- satisfy:    satisfy the config file's conditions if possible\n- status:     determine if the config file's conditions are met\n- types:      list types and their usage information\n```\n\nLet's explore these in more depth:\n\n## Assertions and Config Files\n\nAt the heart of bork is making **assertions** in a **declarative** manner via\nthe `ok` function. That is, you tell it *what* you want the system to look like\ninstead of *how* to make it look like that. An assertion takes a **type** and a\nnumber of arguments. It invokes the type's handler function with an *action*\nsuch as `status`, `install`, or `upgrade`, which determines the imperative\ncommands needed to test the assertion or bring it up to date. There are a number\nof included types in the `types` directory, and bork makes it easy to create\nyour own.\n\nHere's a basic example:\n\n```bash\nok brew                                       # presence and updatedness of Homebrew\nok brew git                                   # presence and updatedness of Homebrew git package\nok directory $HOME/code                       # presence of the ~/code directory\nok github $HOME/code/dotfiles mattly/dotfiles # presence, drift of git repository in ~/code/dotfiles\ncd $HOME\nfor file in $HOME/code/dotfiles/configs/.[!.]*\ndo                                            # for each file in ~/code/dotfiles/configs,\n  ok symlink \"$(basename $file)\" $file       # presense of a symlink to file in ~ with a leading dot\ndone\n```\n\nWhen run, bork will test each `ok` assertion and determine if it's met or not.\nIf not, bork can go ahead and *satisfy* the assertion by installing, upgrading, or\naltering the configuration of the item to match the assertion. It will then test\nthe assertion again. Declarations are idempotent -- if the assertion is already\nmet, bork will not do anything.\n\nWhen you're happy with your config script, you can compile it to a standalone\nscript which does not require bork to run. The compiled script can be passed\naround via curl, scp or the like and run on completely new systems.\n\n## Assertion Types\n\nYou can run `bork types` from the command line to get a list of the assertion types\nand some basic information about their usage and options.\n\n### Generic assertions\n```\n          check: runs a given command.  OK if returns 0, FAILED otherwise.\n```\n\n### File System\n```\n      directory: asserts presence of a directory\n           file: asserts the presence, checksum, owner and permissions of a file\n       download: asserts the presence of a file compared to an http(s) url\n        symlink: assert presence and target of a symlink\n```\n\n### Source Control\n```\n            git: asserts presence and state of a git repository\n         github: front-end for git type, uses github urls\n```\n\n### Language Package Managers\n```\n            gem: asserts the presence of a gem in the environment's ruby\n            npm: asserts the presence of a nodejs module in npm's global installation\n            pip: asserts presence of packages installed via pip\n          pipsi: asserts presence of pipsi or packages installed via pipsi\n            apm: asserts the presence of an atom package\n         go-get: asserts the presence of a go package\n```\n\n### Mac OS X specific\n```\n           brew: asserts presence of packages installed via Homebrew on Mac OS X\n       brew-tap: asserts a Homebrew formula repository has been tapped; does NOT assert updatedness of a tap's formula. Use `ok brew` for that.\n           cask: asserts presence of apps installed via caskroom.io on Mac OS X\n       defaults: asserts settings for OS X's 'defaults' system\n            mas: asserts a Mac app is installed and up-to-date from the App Store\n                 via the 'mas' utility https://github.com/argon/mas\n         scutil: verifies OS X machine name with scutil\n```\n\n### Linux specific:\n```\n            apt: asserts packages installed via apt-get on Debian or Ubuntu Linux\n            yum: asserts packages installed via yum on CentOS or RedHat Linux\n         zypper: asserts packages installed via zypper (SUSE)\n```\n\n### User management (currently Linux-only)\n```\n          group: asserts presence of a unix group (Linux only, for now)\n           user: assert presence of a user on the system\n```\n\n### UNIX utilities\n```\n       iptables: asserts presence of iptables rule\n```\n\n## Runtime Operations\n\nPer the usage guide, bork has a few main modes of operation:\n\n- `status`: Reports on the status of the assertions in a config file.\n- `satisfy`: Checks the status of assertions in a config file, satisfying them\n  where needed.\n- `compile`: Compiles a config file to a standalone script.\n- `check`: Performs a status report on a single assertion.\n- `do`: Performs a satisfy operation on a single assertion.\n\n### bork status myconfig.sh\n\nThe `status` command will confirm that assertions are met or not, and output\ntheir status. It will not take any action to satisfy those assertions. There are\na handful of statuses an assertion can return, and this since this mode is the\nclosest bork can do to a true `dry run`(*) you can use it to test a script\nagainst a pre-existing machine.\n\n* Some types, such as `git`, need to modify local state by talking to the network\n(such as performing `git fetch`), without modifying the things the assertion aims\nto check.\n\nThe status command will give you output such as:\n\n```\noutdated: brew\nok: brew git\nmissing: brew fish\nok: directory /Users/mattly/code/mattly\nconflict (upgradable): github mattly/dotfiles\nlocal git repository has uncommitted changes\nok: symlink /Users/mattly/.gitignore /Users/mattly/code/mattly/dotfiles/configs/gitignore\nconflict (clobber required): symlink /Users/mattly/.lein /Users/mattly/code/mattly/dotfiles/configs/lein\nnot a symlink: /Users/mattly/.lein\nmismatch (upgradable): defaults com.apple.dock tilesize integer 36\nexpected type: integer\nreceived type: float\nexpected value: 36\nreceived value: 55\n```\n\nEach item reports its status like so:\n\n- `ok`: The assertion is met as best we can determine.\n- `missing`: The assertion is not met, and no trace of it ever being met was found.\n- `outdated`: The assertion is met, but can be upgraded to a newer version.\n- `mismatch (upgradable)`: The assertion is not met as specified, something is\n  different. It can be satisfied easily. An explanation will be given.\n- `conflict (upgradable)`: The assertion is not met as specified. It can be\n  satisfied easily, but doing so may result in data loss.\n- `conflict (clobber required)`: The assertion is not met as specified. Bork\n  cannot currently satisfy this assertion. In the future, it will be able to,\n  but doing so may result in data loss.\n\n### bork check ok github mattly/dotfiles\n\nThe `check` command will take a single assertion on the command line and perform\na `status` check as above for it.\n\n### bork satisfy myconfig.sh\n\nThe `satisfy` command is where the real magic happens. For every assertion in\nthe config file, bork will check its status as described in the `status` command\nabove, and if it is not `ok` it will attempt to make it `ok`, typically via\n*installing* or *upgrading* something -- but sometimes a *conflict* is detected\nwhich could lose data, such as a local git repository having uncommitted\nchanges. In that case, bork will warn you about the problem and ask if you want\nto proceed. Sometimes conflicts are detected which bork does not know how to\nresolve — it will warn you about the problem so you can fix it yourself.\n\n### bork do ok github mattly/dotfiles\n\nThe `do` command will take a single assertion on the command line and perform a\n`satisfy` operation on it as above.\n\n### bork compile myconfig.sh\n\nThe `compile` command will output to STDOUT a standalone shell script that does\nnot require bork to run. You may pass this around as with any file via curl or\nscp or whatever you like and run it. Any sub-configs via `include` will be\nincluded in the output, and any type that needs to include resources to do what\nit does, such as the `file` type, will include their resources in the script as\nbase64 encoded data.\n\n### Custom Types\n\nWriting new types is pretty straightforward, and there is a guide to writing\nthem in the `docs/` directory. If you wish to use a type that is not in bork's\n`types` directory, you can let bork know about it with the `register`\ndeclaration:\n\n```bash\nregister etc/pgdb.sh\nok pgdb my_app_db\n```\n\n### Composing Config Files\n\nYou may compose config files into greater operations with the `include`\ndirective with a path to a script relative to the current script's directory.\n\n```bash\n# this is main.sh\ninclude databases.sh\ninclude etc/projects.sh\n```\n\n```bash\n# this is etc/projects.sh\ninclude project-one.sh\ninclude project-two.sh\n# these will be read from the etc/ directory\n```\n\n### Taking Further Action on Changes\n\nBork doesn't have callbacks per-se, but after each assertion there are a handful\nof functions you can call to take further action:\n\n```bash\nok brew fish\nif did_install; then\n  sudo echo \"/usr/local/bin/fish\" \u003e\u003e /etc/shells\n  chsh -s /usr/local/bin/fish\nfi\n```\nThere are four functions to help you take further actions on change:\n\n- `did_install`: did the previous assertion result in the item being installed\n  from scratch?\n- `did_upgrade`: did the previous assertion result in the existing item being\n  upgraded?\n- `did_update`: did the previous assertion result in either the item being\n  installed or upgraded?\n- `did_error`: did attempting to install or upgrade the previous assertion\n  result in an error?\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch: `git checkout -b feature/my-new-feature`\n3. Commit your changes: `git commit -am 'Add some feature'`\n4. Push to the branch: `git push origin feature/my-new-feature`\n5. Submit a pull request\n\n### Contribution Guidelines\n\n1. Prefer clarity of intent over brevity. Bash can be an obtuse language, but it\n   doesn't *have* to be. Many people have said bork has some of the clearest\n   bash code they've ever seen, and that's a standard to strive for.\n\n2. Favor helper abstractions over arbitrary platform-specific checks. See\n   [`md5cmd`](lib/helpers/md5cmd.sh), [`http`](lib/helpers/http.sh), and\n   [`permission_cmd`](lib/helpers/permission_cmd.sh), and look at how they're\n   used.\n\n3. Types are independent, stateless, and atomic. Do not attempt to maintain a\n   cache in a type file unless you're talking to the network. An assertion is\n   the *whole* of the assertion — don't attempt to create a multi-stage\n   assertion type that depends on maintaining state. Find a way to express the\n   whole of the assertion in one go.\n\n4. Leave Dependency Management to the user. Is a needed binary not installed for\n   a type? Return `$STATUS_FAILED_PRECONDITION` in your status check. Let the\n   user decide the best way to satisfy any dependencies.\n\n## Community\n\nFeel free to join us in IRC:\n\n- Hostname: `irc.freenode.org`\n- Channel: `#bork.sh`\n- [Web IRC client in case you don't have a native one](https://kiwiirc.com/client/irc.freenode.net/bork.sh)\n\n## Requirements / Dependencies\n\n* Bash 3.2\n\n## Version\n\n0.10.0\n\n## License\n\n[Apache License 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattly%2Fbork","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmattly%2Fbork","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattly%2Fbork/lists"}