chore: remove Ruby implementation and tooling
This commit is contained in:
Micheal Wilkinson
252
README.md
252
README.md
@@ -1,228 +1,74 @@
|
||||
# homesick
|
||||
|
||||
[](http://badge.fury.io/rb/homesick)
|
||||
[](https://travis-ci.org/technicalpickles/homesick)
|
||||
[](https://gemnasium.com/technicalpickles/homesick)
|
||||
[](https://coveralls.io/r/technicalpickles/homesick)
|
||||
[](https://codeclimate.com/github/technicalpickles/homesick)
|
||||
[](https://gitter.im/technicalpickles/homesick)
|
||||
|
||||
Your home directory is your castle. Don't leave your dotfiles behind.
|
||||
|
||||
Homesick is sorta like [rip](http://github.com/defunkt/rip), but for dotfiles. It uses git to clone a repository containing dotfiles, and saves them in `~/.homesick`. It then allows you to symlink all the dotfiles into place with a single command.
|
||||
This repository now contains a Go implementation of Homesick. A dotfiles repository is called a castle and should contain a `home/` directory with files to link into your `$HOME`.
|
||||
|
||||
We call a repository that is compatible with homesick to be a 'castle'. To act as a castle, a repository must be organized like so:
|
||||
## Build
|
||||
|
||||
- Contains a 'home' directory
|
||||
- 'home' contains any number of files and directories that begin with '.'
|
||||
Build with just:
|
||||
|
||||
To get started, install homesick first:
|
||||
```bash
|
||||
just go-build
|
||||
```
|
||||
|
||||
gem install homesick
|
||||
Or directly with Go:
|
||||
|
||||
Next, you use the homesick command to clone a castle:
|
||||
```bash
|
||||
go build -o dist/homesick-go ./cmd/homesick
|
||||
```
|
||||
|
||||
homesick clone git://github.com/technicalpickles/pickled-vim.git
|
||||
## Commands
|
||||
|
||||
Alternatively, if it's on github, there's a slightly shorter way:
|
||||
Implemented commands:
|
||||
|
||||
homesick clone technicalpickles/pickled-vim
|
||||
- `clone URI [CASTLE_NAME]`
|
||||
- `list`
|
||||
- `show_path [CASTLE]`
|
||||
- `status [CASTLE]`
|
||||
- `diff [CASTLE]`
|
||||
- `link [CASTLE]`
|
||||
- `unlink [CASTLE]`
|
||||
- `track FILE [CASTLE]`
|
||||
- `version`
|
||||
|
||||
With the castle cloned, you can now link its contents into your home dir:
|
||||
Not yet implemented:
|
||||
|
||||
homesick link pickled-vim
|
||||
- `pull`
|
||||
- `push`
|
||||
- `commit`
|
||||
- `destroy`
|
||||
- `cd`
|
||||
- `open`
|
||||
- `exec`
|
||||
- `exec_all`
|
||||
- `rc`
|
||||
- `generate`
|
||||
|
||||
You can remove symlinks anytime when you don't need them anymore
|
||||
## Behavior Suite
|
||||
|
||||
homesick unlink pickled-vim
|
||||
The repository includes a Docker-based behavior suite that validates filesystem and git outcomes for the implemented commands.
|
||||
|
||||
If you need to add further configuration steps you can add these in a file called '.homesickrc' in the root of a castle. Once you've cloned a castle with a .homesickrc run the configuration with:
|
||||
Run behavior suite:
|
||||
|
||||
homesick rc CASTLE
|
||||
```bash
|
||||
just behavior
|
||||
```
|
||||
|
||||
The contents of the .homesickrc file must be valid Ruby code as the file will be executed with Ruby's eval construct. The .homesickrc is also passed the current homesick object during its execution and this is available within the .homesickrc file as the 'self' variable. As the rc operation can be destructive the command normally asks for confirmation before proceeding. You can bypass this by passing the '--force' option, for example `homesick rc --force CASTLE`.
|
||||
Verbose behavior suite output:
|
||||
|
||||
If you're not sure what castles you have around, you can easily list them:
|
||||
```bash
|
||||
just behavior-verbose
|
||||
```
|
||||
|
||||
homesick list
|
||||
## Testing
|
||||
|
||||
To pull your castle (or all castles):
|
||||
Run all Go tests:
|
||||
|
||||
homesick pull --all|CASTLE
|
||||
```bash
|
||||
just go-test
|
||||
```
|
||||
|
||||
To commit your castle's changes:
|
||||
## License
|
||||
|
||||
homesick commit CASTLE
|
||||
|
||||
To push your castle:
|
||||
|
||||
homesick push CASTLE
|
||||
|
||||
To open a terminal in the root of a castle:
|
||||
|
||||
homesick cd CASTLE
|
||||
|
||||
To open your default editor in the root of a castle (the $EDITOR environment variable must be set):
|
||||
|
||||
homesick open CASTLE
|
||||
|
||||
To execute a shell command inside the root directory of a given castle:
|
||||
|
||||
homesick exec CASTLE COMMAND
|
||||
|
||||
To execute a shell command inside the root directory of every cloned castle:
|
||||
|
||||
homesick exec_all COMMAND
|
||||
|
||||
Not sure what else homesick has up its sleeve? There's always the built in help:
|
||||
|
||||
homesick help
|
||||
|
||||
If you ever want to see what version of homesick you have type:
|
||||
|
||||
homesick version|-v|--version
|
||||
|
||||
## Docker Behavior Validation (Ruby vs Go)
|
||||
|
||||
To preserve behavior while migrating from Ruby to Go, this repository includes a containerized behavior suite that runs Homesick commands in a clean environment and validates filesystem and git outcomes.
|
||||
|
||||
The suite creates a dedicated git repository inside the container to act as a test castle fixture, then validates behavior for:
|
||||
|
||||
- clone
|
||||
- link / unlink
|
||||
- track
|
||||
- list / show_path
|
||||
- status / diff
|
||||
- version
|
||||
|
||||
Run against the current Ruby implementation:
|
||||
|
||||
./script/run-behavior-suite-docker.sh
|
||||
|
||||
Show full command output (including internal Homesick status lines) when needed:
|
||||
|
||||
./script/run-behavior-suite-docker.sh --verbose
|
||||
|
||||
This runner now builds an Alpine-based container and installs runtime dependencies with `apk`, so behavior validation is not tied to a Ruby base image.
|
||||
|
||||
Run against a future Go binary (example path):
|
||||
|
||||
HOMESICK_CMD="/workspace/dist/homesick" ./script/run-behavior-suite-docker.sh
|
||||
|
||||
The command under test is controlled with the `HOMESICK_CMD` environment variable. By running the same suite for both implementations, you can verify parity at the behavior level.
|
||||
|
||||
## Go Scaffold
|
||||
|
||||
Initial Go scaffolding now lives under [cmd/homesick](cmd/homesick) and [internal/homesick](internal/homesick).
|
||||
|
||||
Build the Go binary:
|
||||
|
||||
just go-build
|
||||
|
||||
Run behavior validation against the Go binary:
|
||||
|
||||
HOMESICK_CMD="/workspace/dist/homesick-go" just behavior-go
|
||||
|
||||
At this stage, the Go implementation includes a subset of commands (`clone`, `list`, `show_path`, `status`, `diff`, `version`) and intentionally reports clear errors for commands that are not ported yet.
|
||||
|
||||
## .homesick_subdir
|
||||
|
||||
`homesick link` basically makes symlink to only first depth in `castle/home`. If you want to link nested files/directories, please use .homesick_subdir.
|
||||
|
||||
For example, when you have castle like this:
|
||||
|
||||
castle/home
|
||||
`-- .config
|
||||
`-- fooapp
|
||||
|-- config1
|
||||
|-- config2
|
||||
`-- config3
|
||||
|
||||
and have home like this:
|
||||
|
||||
$ tree -a
|
||||
~
|
||||
|-- .config
|
||||
| `-- barapp
|
||||
| |-- config1
|
||||
| |-- config2
|
||||
| `-- config3
|
||||
`-- .emacs.d
|
||||
|-- elisp
|
||||
`-- inits
|
||||
|
||||
You may want to symlink only to `castle/home/.config/fooapp` instead of `castle/home/.config` because you already have `~/.config/barapp`. In this case, you can use .homesick_subdir. Please write "directories you want to look up sub directories (instead of just first depth)" in this file.
|
||||
|
||||
castle/.homesick_subdir
|
||||
|
||||
.config
|
||||
|
||||
and run `homesick link CASTLE`. The result is:
|
||||
|
||||
~
|
||||
|-- .config
|
||||
| |-- barapp
|
||||
| | |-- config1
|
||||
| | |-- config2
|
||||
| | `-- config3
|
||||
| `-- fooapp -> castle/home/.config/fooapp
|
||||
`-- .emacs.d
|
||||
|-- elisp
|
||||
`-- inits
|
||||
|
||||
Or `homesick track NESTED_FILE CASTLE` adds a line automatically. For example:
|
||||
|
||||
homesick track .emacs.d/elisp castle
|
||||
|
||||
castle/.homesick_subdir
|
||||
|
||||
.config
|
||||
.emacs.d
|
||||
|
||||
home directory
|
||||
|
||||
~
|
||||
|-- .config
|
||||
| |-- barapp
|
||||
| | |-- config1
|
||||
| | |-- config2
|
||||
| | `-- config3
|
||||
| `-- fooapp -> castle/home/.config/fooapp
|
||||
`-- .emacs.d
|
||||
|-- elisp -> castle/home/.emacs.d/elisp
|
||||
`-- inits
|
||||
|
||||
and castle
|
||||
|
||||
castle/home
|
||||
|-- .config
|
||||
| `-- fooapp
|
||||
| |-- config1
|
||||
| |-- config2
|
||||
| `-- config3
|
||||
`-- .emacs.d
|
||||
`-- elisp
|
||||
|
||||
## Supported Ruby Versions
|
||||
|
||||
Homesick is tested on the following Ruby versions:
|
||||
|
||||
- 2.2.6
|
||||
- 2.3.3
|
||||
- 2.4.0
|
||||
|
||||
## Note on Patches/Pull Requests
|
||||
|
||||
- Fork the project.
|
||||
- Make your feature addition or bug fix.
|
||||
- Add tests for it. This is important so I don't break it in a future version unintentionally.
|
||||
- Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
|
||||
- Send me a pull request. Bonus points for topic branches.
|
||||
|
||||
## Need homesick without the ruby dependency?
|
||||
|
||||
Check out [homeshick](https://github.com/andsens/homeshick).
|
||||
|
||||
## Copyright
|
||||
|
||||
Copyright (c) 2010 Joshua Nichols. See LICENSE for details.
|
||||
See `LICENSE`.
|
||||
|
||||
Reference in New Issue
Block a user