{"id":15712341,"url":"https://github.com/xwmx/bindle","last_synced_at":"2025-05-06T20:44:31.694Z","repository":{"id":24655624,"uuid":"28065735","full_name":"xwmx/bindle","owner":"xwmx","description":"A configuration and dotfile management tool for your personal unix-like computer.","archived":false,"fork":false,"pushed_at":"2020-10-07T06:14:21.000Z","size":454,"stargazers_count":54,"open_issues_count":0,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-22T18:26:03.931Z","etag":null,"topics":["bash","bootstrap","config","configuration","dotfiles","linux","shell","terminal","unix"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xwmx.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}},"created_at":"2014-12-16T02:00:48.000Z","updated_at":"2025-02-21T01:05:22.000Z","dependencies_parsed_at":"2022-07-27T04:46:42.502Z","dependency_job_id":null,"html_url":"https://github.com/xwmx/bindle","commit_stats":null,"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xwmx%2Fbindle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xwmx%2Fbindle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xwmx%2Fbindle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xwmx%2Fbindle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xwmx","download_url":"https://codeload.github.com/xwmx/bindle/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252769069,"owners_count":21801373,"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","bootstrap","config","configuration","dotfiles","linux","shell","terminal","unix"],"created_at":"2024-10-03T21:15:41.868Z","updated_at":"2025-05-06T20:44:31.651Z","avatar_url":"https://github.com/xwmx.png","language":"Shell","readme":"[![Build Status](https://travis-ci.org/xwmx/bindle.svg?branch=master)](https://travis-ci.org/xwmx/bindle)\n\n     _____  ___  _____  _____  ____   _____\n    /  _  \\/___\\/  _  \\|  _  \\/  _/  /   __\\\n    |  _  \u003c|   ||  |  ||  |  ||  |---|   __|\n    \\_____/\\___/\\__|__/|_____/\\_____/\\_____/\n\n# bindle\n\n`bindle` is a configuration and dotfile management tool for your personal\nunix-like computer.\n\n`bindle` provides an easy way to manage a user's configuration files,\nparticularly:\n\n- dotfiles,\n- user binaries and scripts (ie, anything in `$HOME/bin`),\n- scripts for configuration and bootstrapping.\n\n`bindle` compliments manual configuration and versioning. `bindle` tracks files\nin a git repository with a simple and logical directory structure that works\ngreat for dotfile versioning with or without the `bindle` program itself.\n`bindle` is written as a single well-structured shell script and can be\nused with any modern unix-like system.\n\nSee [xwmx/dotfiles](https://github.com/xwmx/dotfiles) for an\nexample of a configuration managed with `bindle`.\n\n## Installation\n\n### Homebrew\n\nTo install with [Homebrew](http://brew.sh/):\n\n```bash\nbrew tap xwmx/taps\nbrew install bindle\n```\n\n### npm\n\nTo install with [npm](https://www.npmjs.com/package/bindle-cli):\n\n```bash\nnpm install --global bindle-cli\n```\n\n### bpkg\n\nTo install with [bpkg](http://www.bpkg.io/):\n\n```bash\nbpkg install xwmx/bindle\n```\n\n### Manual\n\nTo install manually, simply add the `bindle` script to your `$PATH`. If\nyou already have a `~/bin` directory, you can use the following command:\n\n```bash\ncurl -L https://raw.github.com/xwmx/bindle/master/bindle \\\n  -o ~/bin/bindle \u0026\u0026 chmod +x ~/bin/bindle\n```\n\n## Usage\n\n### Help Information\n\nYou can view the usage and help information by running `bindle` with no\narguments or with the `--help` or `-h` options.\n\n### Setup\n\nIf you don't currently have a local repository tracking your dotfiles,\nyou can create one using\n\n```bash\nbindle init\n```\n\nThis will initialize a git repository at `$HOME/.bindle` with the following\nstructure:\n\n    ~/.bindle\n    ├── .gitignore\n    ├── home/\n    ├── bin/\n    ├── local/\n    └── scripts/\n        ├── bootstrap/\n        ├── configure/\n        ├── customize/\n        └── install/\n\nYou can change the location used for storing dotfiles by adding a\n`.bindlerc` file at `$HOME/.bindlerc` and setting the `$BINDLEPATH` variable to\nthe desired location:\n\n```bash\nexport BINDLEPATH=\"/a/custom/path\"\n```\n\n### Overview\n\n#### home\n\nContains all dotfiles and directories from `$HOME` that have been added to the\nrepository.\n\nThe `bindle` command assumes that any items at the root level of this directory\nare 1) dotfiles (files and directories with a `.` prefix like `.bashrc` or\n`.vim`) and 2) normally exist at your `$HOME` path, aka `~/`, which is the\ntop level of your user account's home directory.\n\nTo list existing dotfiles in `$HOME`, use `bindle list`\n\n```bash\nbindle list\n```\n\nTo track items from `$HOME`, use `bindle track`:\n\n```bash\nbindle track .bashrc\n```\n\nThis adds the file or directory to `BINDLEPATH/home` and creates a symbolic link\nin `$HOME` referencing the file or directory.\n\nOnce you've added a file, you need to commit it to the repository.\n\n```bash\nbindle commit\n```\n\nThis will `git add` the changed files and do a `git commit`. See `bindle\nhelp commit` for more information.\n\nTo list all tracked files:\n\n```bash\nbindle list tracked\n```\n\nIf you want to stop tracking a dotfile or directory, run `bindle untrack`:\n\n```bash\nbindle untrack .bashrc\n```\n\nThis removes the symbolic link in `$HOME` and copies the original file back to\n`$HOME` from `$BINDLEPATH/home`.\n\n###### Example\n\nAn example `bindle`-managed home directory:\n\n[xwmx/dotfiles/home](https://github.com/xwmx/dotfiles/tree/master/home)\n\n#### bin\n\n`bin` is intended as a directory for executables and scripts that you'd like to\ntrack along with your dotfiles. To make the executables in this directory\naccessible to your shell environment, include the following line in your\n`.bashrc` or equivalent:\n\n```bash\nPATH=\"${BINDLEPATH}/bin:${PATH}\"\n```\n\n###### Example\n\nAn example `bindle`-managed bin directory:\n\n[xwmx/dotfiles/bin](https://github.com/xwmx/dotfiles/tree/master/bin)\n\n#### local\n\nThis directory is excluded from the git repository, and therefore can be\nused for storing things related to the configuration that you don't want\nto track and don't want in the default directories.\n\n#### scripts\n\n`scripts` contains several subdirectories for contriguration scripts.\nScripts or programs in these directories can be written in any language.\n`bindle` makes no assumptions about any of the scripts in these directories\nand will simply run them.\n\nTo run a script that is located at `$BINDLEPATH/scripts/example.bash`:\n\n```bash\nbindle run example.bash\n```\n\nScripts can be organized in subdirectories. Newly-created `bindle`\nprojects contain several placeholder directories: `bootstrap`,\n`configure`, `customize`, `install`.\n\nTo run a script that is located at `$BINDLEPATH/scripts/install/example.bash`:\n\n```bash\nbindle run install/example.sh\n```\n\nFor more information, see `bindle help run`\n\n###### Example\n\nAn example `bindle`-managed scripts directory:\n\n[xwmx/dotfiles/script\n](https://github.com/xwmx/dotfiles/tree/master/script)\n\n##### scripts/bootstrap\n\nScripts that bootstrap the user account and user-controlled parts of the\nsystem.\n\nFor example, bootstrap scripts could set up some default folders and/or call a\nseries of `install`, `configure`, and `customize` scripts. Generally, a\nbootstrap script would only be called once, during an initial setup.\n\n##### scripts/install\n\nScripts that install programs, such as with package management systems.\n\nFor example, you could have a bash script that contains commands for installing\nprograms via a system-wide package manager like [homebrew](http://brew.sh/) or\na language-specific one like [LuaRocks](http://luarocks.org/).\n\n##### scripts/configure\n\nScripts that run perform system configuration operations, like setting\npreferences.\n\n##### scripts/customize\n\nScripts that customize any aspect of the configuration or system.\n\n#### .gitignore\n\n`.gitignore` can be used to exclude sensitive information\nfrom directories in the repository. When generating a new repository, `bindle`\nexcludes everything in any added `.ssh` directory except for the\n`.ssh/config`.\n\n`.gitignore` is also useful for dot directories that have both config files\nand large temp or cache files. For example, a `.rbenv` directory for the\n[rbenv](https://github.com/sstephenson/rbenv) tool contains both\nconfiguration files and entire Ruby installations that are many\ngigabytes in size. You can use `.gitignore` to exclude the ruby\ninstallation directories while tracking the configuration files.\n\n### Git Commands\n\nTo view the help and usage information for any command, use:\n\n    bindle help \u003ccommand-name\u003e\n\n#### `add`\n\n```text\nUsage:\n  bindle add \u003cfilename\u003e [--force]\n\nDescription:\n  `add` is an alias for `track`. For more information, run:\n    `bindle help track`\n```\n\n#### `commands`\n\n```text\nUsage:\n  bindle commands [--raw]\n\nOptions:\n  --raw  Display the command list without formatting.\n\nDescription:\n  Display the list of available commands.\n```\n\n#### `commit`\n\n```text\nUsage:\n  bindle commit [\u003cmessage\u003e]\n\nDescription:\n  Commit the current changes to git. If a message is provided, it will be used\n  as the commit message. Otherwise, git will open your default editor.\n```\n\n#### `dir`\n\n```text\nUsage:\n  bindle dir\n\nDescription:\n  Print the current value of $BINDLEPATH\n```\n\n#### `dotfiles`\n\n```text\nUsage:\n  bindle dotfiles\n\nDescription:\n  List all dotfiles. Alias for `bindle status`.\n```\n\n#### `edit`\n\n```text\nUsage:\n  bindle edit\n  bindle edit [\u003cfilename\u003e]\n\nDescription:\n  Open a tracked file or, when no filename is specified, the entire tracked\n  repository in you $EDITOR, currently set to 'vim'.\n```\n\n#### `git`\n\n```text\nUsage:\n  bindle git command [--options] [\u003carguments\u003e]\n\nDescription:\n  Run a git command within the $BINDLEPATH directory.\n```\n\n#### `help`\n\n```text\nsage:\n  bindle help [\u003ccommand\u003e]\n\nDescription:\n  Display help information for bindle or a specified command.\n```\n\n#### `init`\n\n```text\nUsage:\n  bindle init [\u003csource-repository\u003e [--initialize-submodules]] [\u003cbindlepath\u003e] [--skip-bindlerc]\n\nOptions:\n  --initialize-submodules  Initialize repository submodules when used with a\n                           \u003csource-repository\u003e argument.\n  --skip-bindlerc          Don't generate a bindlerc file.\n\nDescription:\n  Create initial repository file structure.\n\n  When provided with a URL as the first argument or a second argument the git\n  repository at that URL is cloned and used as the tracking repository.\n\n  When provided with an absolute path as the lone argument or second argument\n  after a repository URL, the initial repository is created at the specified\n  path and a configuration file is created at $HOME/.bindlerc with that\n  location set as the $BINDLEPATH.\n```\n\n#### `link`\n\n```text\nUsage:\n  bindle link [\u003cfilename\u003e] [--overwrite [--with-backup]]\n\nOptions:\n  --overwrite    Overwrite any files that exist in the directory where links\n                 are being created, meaning that any conflicting files will be\n                 deleted and links to the corresponding repository file will\n                 be created.\n  --with-backup  When used in combination with --overwrite, any overwritten\n                 files are first renamed with a '.bak' extension. If a file\n                 with the same name plus '.bak' extension already exists,\n                 nothing is done to this file and no link is created.\n\nDescription:\n  Create a link in $HOME that references the corresponding item in the\n  tracked directory.\n\n  By default, the command links all files that exist in the tracked directory.\n  If a filename is passed to the link command, then it only acts on that file.\n```\n\n#### `list`\n\n```text\nUsage:\n  bindle list [tracked | untracked] [\u003csearch-string\u003e]\n\nDescription:\n  List all files in $HOME.\n\n  If 'tracked' or 'untracked' as passed as arguments to 'list', then only the\n  files with those statuses are listed. When provided with a seach string, all\n  matching filenames will be printed.\n```\n\n#### `pull`\n\n```text\nUsage:\n  bindle pull\n\nDescription:\n  Pull latest changes from the remote repository.\n```\n\n#### `push`\n\n```text\nUsage:\n  bindle push\n\nDescription:\n  Push local commits to the remote repository.\n```\n\n#### `rename`\n\n```text\nUsage:\n  bindle rename \u003cold-filename\u003e \u003cnew-filename\u003e\n\nDecription:\n  Rename a tracked file and its corresponding link in $HOME.\n```\n\n#### `restore`\n\n```text\nUsage:\n  bindle restore \u003cfilename\u003e\n\nDescription:\n  `restore` is an alias for `untrack`. For more information, run:\n    `bindle help untrack`\n```\n\n#### `run`\n\n```text\nUsage:\n  bindle run ( list | \u003cscript-name\u003e )\n\nDescription:\n  Run and list scripts.\n\n  Scripts can be added to:\n    $BINDLEPATH/scripts/\n```\n\n#### `scripts`\n\n```text\nUsage:\n  bindle scripts\n\nDescription:\n  List all scripts. Alias for `bindle run`.\n```\n\n#### `status`\n\n```text\nUsage:\n  bindle status\n\nDescription:\n  List status of files in $HOME with filenames matching those in\n  $BINDLEPATH/home/.\n\n  Indicators display information about the status of each entry:\n   ✅   - Identical, indicating a valid symbolic link to the tracked file\n     e  - A file exists, but it's not linked to tracked file\n      x - No file exists\n```\n\n#### `submodules`\n\n```text\nUsage:\n  bindle submodules ( sync | update )\n\nSubcommands:\n  sync    Sync all submodules with the current head commit. This usually be\n          should be performed after a `bindle pull`. Equivalent git command:\n            git submodule update --recursive --init\n  update  Update all first-level submodules to the latest commit in each\n          submodule's origin repository. Equivalent git command:\n            git submodule update --init --remote\n```\n\n#### `sync`\n\n```text\nUsage:\n  bindle sync\n\nDescription:\n  Pull latest changes from the remote repository and sync submodules.\n```\n\n#### `track`\n\n```text\nUsage:\n  bindle track \u003cfilename\u003e [--force]\n\nOptions:\n  --force  Overwrite files and folders in the repository that have the same\n           name as the item(s) being added.\n\nDescription:\n  Track the specified file, adding it to the repository and adding a link in\n  $HOME to the tracked file.\n```\n\n#### `tracked`\n\n```text\nUsage:\n  bindle tracked\n\nDescription:\n  List all tracked dotfiles in $HOME.\n```\n\n#### `unlink`\n\n```text\nUsage:\n  bindle unlink [\u003cfilename\u003e]\n\nDescription:\n  Remove symlinks in $HOME.\n\n  By default, the command removes all of the symlinks pointing to items in\n  tracked directory. If a filename is passed to the unlink command, then it\n  only acts on symlinks to that file.\n```\n\n#### `untrack`\n\n```text\nUsage:\n  bindle untrack \u003cfilename\u003e\n\nDescription:\n  Unlink the specified file and move it from the tracked location in the\n  repository back to original location in $HOME.\n```\n\n#### `untracked`\n\n```text\nUsage:\n  bindle untracked\n\nDescription:\n  List all untracked dotfiles in $HOME.\n```\n\n#### `version`\n\n```text\nUsage:\n  bindle ( version | --version )\n\nDescription:\n  Display the current program version.\n```\n\n## More Resources\n\n- [xwmx/dotfiles](https://github.com/xwmx/dotfiles)\n- [xwmx/dotfile-research](https://github.com/xwmx/dotfile-research)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxwmx%2Fbindle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxwmx%2Fbindle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxwmx%2Fbindle/lists"}