{"id":21666885,"url":"https://github.com/tubbo/homer","last_synced_at":"2025-04-12T01:18:15.528Z","repository":{"id":23648518,"uuid":"27018941","full_name":"tubbo/homer","owner":"tubbo","description":"The home directory management tool.","archived":false,"fork":false,"pushed_at":"2023-12-15T08:21:38.000Z","size":3550,"stargazers_count":27,"open_issues_count":6,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-12T01:18:09.371Z","etag":null,"topics":["dotfiles","shell","sync","zsh"],"latest_commit_sha":null,"homepage":"https://tubbo.github.io/homer","language":"Shell","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/tubbo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2014-11-23T01:53:35.000Z","updated_at":"2024-05-06T08:56:41.000Z","dependencies_parsed_at":"2023-12-15T09:40:13.868Z","dependency_job_id":null,"html_url":"https://github.com/tubbo/homer","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tubbo%2Fhomer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tubbo%2Fhomer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tubbo%2Fhomer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tubbo%2Fhomer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tubbo","download_url":"https://codeload.github.com/tubbo/homer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248501855,"owners_count":21114684,"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":["dotfiles","shell","sync","zsh"],"created_at":"2024-11-25T11:30:03.947Z","updated_at":"2025-04-12T01:18:15.505Z","avatar_url":"https://github.com/tubbo.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Homer\n\n[![Test Status](https://github.com/tubbo/homer/workflows/Tests/badge.svg)][ci]\n[![Build Status](https://github.com/tubbo/homer/workflows/Build/badge.svg)][ci]\n[![Publish Status](https://github.com/tubbo/homer/workflows/Publish/badge.svg)][ci]\n\n![Homer Thinking](https://github.com/tubbo/homer/raw/master/docs/homer-thinking.gif)\n\nHomer is a home directory manager for your shell. Using [Git][git], it\ntracks changes in your home directory configuration from anywhere on\nyour machine. Its goal is to uncover the IDE-like possibilities of the\nshell and make such features more approachable to newer users, while\nstill retaining its usefulness to power users.\n\nHomer is an opinionated, but minimal, framework. While most of what\nit assumes about your environment is strongly enforced across the\nframework, it attempts to assume little about your system, instead\nallowing you to customize your shell the way you see fit. Homer's main\nphilosophy is that having a stellar shell configuration should be\nmuch easier than it is today.\n\n## How It Works\n\nHomer is effectively a Git repo and shell extension manager that is accessible\nfrom anywhere on the machine. It's written entirely in [ZSH][] shell\nscript, but you don't have to use ZSH to gain its benefits. Homer is actually\nnothing more than a set of conventions, some shell scripts to make\ncomplex tasks easier, and some useful/sane defaults for ZSH. Homer's\ncomponents are tools that wrap a Git repository and your ZSH\nconfiguration.\n\nHomer is comparable with tools like [GNU Stow][stow], its main\ndifference is that instead of keeping a directory separate from\n`$HOME` and symlinking the necessary files over from some\nversion-controlled directory when asked, Homer uses the home\ndirectory as a Git repository and ignores any files it doesn't explicitly\ntrack. It also provides ZSH-specific alias and plugin management, which\nStow as a more generalized system does not do. Homer is essentially a tool for\nmanaging any file in your home directory you wish to keep with Git.\n\n## Features\n\n- Syncs home directory configuration with a Git repository\n- Manages shell aliases and custom shell scripts\n- Manages OS packages and custom package repositories\n- Exposes useful attributes and contains a small CLI plugin API that\n  allows for hooking into Homer and adding your own commands.\n\n## Installation\n\nThe easiest way to install Homer is with the one-liner install script:\n\n```bash\n$ curl -o- -L https://homer.psychedeli.ca/install.sh | bash\n```\n\nIt's a good practice to always [view the source code][installer] before\nrunning a command like this, but if you're busy, here's a short\ndescription of what the installer script does:\n\n1. Downloads the latest `.tar.gz` release of Homer\n2. Extracts the source code to a directory in `/tmp`\n3. Runs `sudo make` in the source code directory, this will require you\n   to type in your root password\n4. Removes all files in the `/tmp` directory created by the installer.\n\n### From a Package Manager\n\nAs a package, Homer is available on [Homebrew][brew]:\n\n```bash\n$ brew tap tubbo/homebrew-tap\n$ brew install homer\n```\n\nYou can also install the edge version of Homer, which is the latest\ncommit of 'master' branch, by applying the **--HEAD** switch:\n\n```bash\n$ brew install homer --HEAD\n```\n\n### From Source\n\nBefore installing from source, make sure you have the following hard\ndependencies installed:\n\n- zsh\n- antigen\n- keychain\n- bats (if you're developing on the project)\n\nOnce they're all installed, run the following commands to install to\n`/usr/local`...\n\n```bash\n$ git clone https://github.com/tubbo/homer.git\n$ cd homer\n$ make \u0026\u0026 sudo make install\n```\n\nWhen its installed, run the setup command:\n\n```bash\n$ homer init\n```\n\nThis will create a Git repo in your home directory, add\na `~/.gitignore` file to control it, and some\ndefault ZSH configuration.\n\nIf you already have a home directory repo that was initialized using\nHomer, you can copy it down to your machine with the following command:\n\n```bash\n$ homer init https://url.to/your/home/directory/repo.git\n```\n\nThis will clone the Git repo at the URL provided to `/tmp/homer` without\nactually checking out a working copy. After copying the `.git` directory\n(the actual data contents of the repo) to your home directory, it will\nrun `git reset --hard HEAD` to \"rehydrate\" all the files of the working\ncopy in the home directory rather than in the place it was checked out.\nThis is to ensure that any overwritten files will have a diff to show\nyou what changed, and none of your files that currently exist in the\nhome directory will be accidentally deleted.\n\n## Usage\n\nHomer is primarily used to track files which are located in your home\ndirectory to your Git repository. You can add files that are currently\nuntracked with the `homer save` command:\n\n```bash\n$ homer save .vimrc -m \"Removed vim-rails\"\n```\n\nThis will begin tracking the file at `~/.vimrc` in your home directory\nrepo. A commit will be added using the message in `-m`, and you can run\n`homer update` to sync with the remote at any time.\n\nIf you wish to stop tracking a given configuration file, run `homer\nsave` with the `-r` flag:\n\n```bash\n$ homer save -r .vimrc\n```\n\nThis removes the `~/.vimrc` file from your repo (but retains it in your\nhome directory) and stops tracking it. When no `-m` is given for a\nmessage, the message is derived from the action, command, and filename.\n\n### Idempotency\n\nHomer is designed to keep your local machine's configuration in sync\nwith the configuration that may be stored on a remote Git repository.\nThis could have changes that are not yet on your machine, and Homer\ncan pull those changes down, cleanly, without affecting any files that\nyou may have locally edited.\n\nTo update the current home directory with the remote:\n\n```bash\n$ homer update\n```\n\nYou can also update Homer itself, which is basically re-running the\ninstaller script. To do so, run:\n\n```bash\n$ homer upgrade\n```\n\n### Plugins\n\nHomer provides an easy way to manage ZSH plugins with [Antigen][].\nThese plugins are automatically installed when you `init` your home\ndirectory on a new machine. Antigen is installed automatically upon\ninitialization if it's not already installed. The plugin manifest can be\nfound in `~/etc/plugins.zsh`.\n\nTo install a new plugin:\n\n```bash\n$ homer plugin zsh-users/zsh-syntax-highlighting\n```\n\nAs well as remove them.\n\n```bash\n$ homer plugin zsh-users/zsh-syntax-highlighting -r\n```\n\n### Aliases\n\nHomer can add aliases and save them for later use. These aliases are\nstored in `~/etc/aliases.zsh`, and tracked by Git so they can be shared\nin your home directory repository.\n\nTo add a new alias:\n\n```bash\n$ homer alias gc 'git commit'\n```\n\nReload your shell, and you can now use `gc` as an alias to `git commit`:\n\n```bash\n$ gc -m \"wow this is cool\"\n```\n\nTo delete an alias:\n\n```bash\n$ homer alias -d gc\n```\n\n### User Scripts\n\nIf you write a useful shell script or executable, Homer can copy this\nfile to a directory in your `$PATH`. Homer uses the `~/bin` directory\nfor this purpose, and keeps files in this directory checked in to Git so\nyou can share them in your home directory repo. Upon initialization,\nHomer will also `chmod +x` this entire directory to ensure that files\ncreated within it will default to be executable by the current user.\n\n```bash\n$ homer script bin/find-and-replace-in-project\n$ find-and-replace-in-project\n```\n\nYou can also remove commands from this directory:\n\n```bash\n$ homer script bin/find-and-replace-in-project -r\n```\n\n### Text Editing and Paging\n\nHomer uses the `$EDITOR` and `$PAGER` variables as the backbone for the\n`edit` and `page` (or `e` and `v`) commands used to edit and view text\nfiles, respectively. Text editing and viewing files with a page are two\nof the most common tasks performed within the shell, and Homer helps\nintegrate whatever editor you choose to use seamlessly within your shell\nenvironment.\n\nTo edit text with your `$EDITOR`, run:\n\n```bash\n$ edit some/file.txt\n```\n\nYou can also view files with the `$PAGER` by running:\n\n```bash\n$ page /var/log/system.log\n```\n\nThe `$EDITOR` is set to `vi` by default, and the `$PAGER` is set to\n`less`, but you can change these values in your **~/.zshenv**:\n\n```bash\nexport EDITOR='vim'\nexport PAGER='less -r'\n```\n\n### Conventions\n\nHomer establishes useful conventions on your home directory. It\nuses the **~/bin/** directory to store user-made scripts which are\navailable in the `$PATH`. It creates an **~/etc/** directory and uses that to\nstore files such as **~/etc/plugins.zsh** for defining shell plugins and\n**~/etc/aliases.zsh** for storing shell aliases you wish to recall later.\nNote that you should not edit the manifest files mentioned above manually, the\n`homer alias` and `homer plugin` tools should manage the files for\nyou. Place any ZSH code you wish to load when the shell launches\nin \"initializer\" files within **~/etc/profile.d**, keeping **~/.zshrc** and\n**~/.zshenv** clear.\n\nAs well as creating these initial files, it also runs `git init` in your\nhome directory, effectively making the entire thing a Git repository. In order\nto prevent massive repo sizes and checking in unsafe credentials,\nHomer does not initially add any files to this repo, except for the ones\nit generates. One of these generated files is a `.gitignore`, which ignores all\nfiles in the home directory by default. To add files to the repo, you need to use\n`homer save` or run `git add -f` in your home directory.\n\n## Development\n\nHomer is written entirely in [ZSH][] shell script. It uses [BATS][bats] to\nrun its tests, and a Makefile is provided to run the tests as well as\nbuild/install the project.\n\nTo run tests:\n\n```bash\n$ make test\n```\n\nYou can also use the Makefile to generate a new command:\n\n```bash\n$ make command NAME=foo\n```\n\nThis will generate `bin/homer-foo`, `share/doc/homer/foo.txt`, and\n`test/homer-foo-test.bats` with given templates.\n\nThe Makefile is also used to create releases, which are mostly handled\nby [GitHub Actions][ci]. To create a new release, generate its tag by running:\n\n```bash\n$ make release VERSION=foo\n```\n\nThis will create a new tag and push it to GitHub, where the package will\nbe built, signed, and uploaded as an artifact to a new [GitHub Release][]\n\n### License\n\nHomer uses the MIT License, as described below:\n\n```\nThe MIT License (MIT)\n\nCopyright (c) 2014-2019 Tom Scott\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n```\n\n[git]: http://git-scm.com\n[brew]: http://brew.sh\n[bats]: https://github.com/sstephenson/bats\n[stow]: http://www.gnu.org/software/stow/\n[ci]: https://github.com/tubbo/homer/actions\n[Antigen]: https://github.com/zsh-users/antigen\n[ZSH]: http://zsh.sourceforge.net/\n[installer]: https://github.com/tubbo/homer/blob/master/docs/install.sh\n[GitHub Release]: https://github.com/tubbo/homer/releases\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftubbo%2Fhomer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftubbo%2Fhomer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftubbo%2Fhomer/lists"}