Debian Codegraph @

README.markdown

raw
1 # homesick
2
3 [![Gem Version](https://badge.fury.io/rb/homesick.svg)](http://badge.fury.io/rb/homesick)
4 [![CI](https://github.com/technicalpickles/homesick/actions/workflows/ci.yml/badge.svg)](https://github.com/technicalpickles/homesick/actions/workflows/ci.yml)
5
6 Your home directory is your castle. Don't leave your dotfiles behind.
7
8 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.
9
10 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:
11
12 * Contains a 'home' directory
13 * 'home' contains any number of files and directories that begin with '.'
14
15 To get started, install homesick first:
16
17 gem install homesick
18
19 Next, you use the homesick command to clone a castle:
20
21 homesick clone git://github.com/technicalpickles/pickled-vim.git
22
23 Alternatively, if it's on github, there's a slightly shorter way:
24
25 homesick clone technicalpickles/pickled-vim
26
27 With the castle cloned, you can now link its contents into your home dir:
28
29 homesick link pickled-vim
30
31 You can remove symlinks anytime when you don't need them anymore
32
33 homesick unlink pickled-vim
34
35 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:
36
37 homesick rc CASTLE
38
39 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`.
40
41 If you're not sure what castles you have around, you can easily list them:
42
43 homesick list
44
45 To pull your castle (or all castles):
46
47 homesick pull --all|CASTLE
48
49 To commit your castle's changes:
50
51 homesick commit CASTLE
52
53 To push your castle:
54
55 homesick push CASTLE
56
57 To open a terminal in the root of a castle:
58
59 homesick cd CASTLE
60
61 To open your default editor in the root of a castle (the $EDITOR environment variable must be set):
62
63 homesick open CASTLE
64
65 To execute a shell command inside the root directory of a given castle:
66
67 homesick exec CASTLE COMMAND
68
69 To execute a shell command inside the root directory of every cloned castle:
70
71 homesick exec_all COMMAND
72
73 Not sure what else homesick has up its sleeve? There's always the built in help:
74
75 homesick help
76
77 If you ever want to see what version of homesick you have type:
78
79 homesick version|-v|--version
80
81 ## .homesick_subdir
82
83 `homesick link` basically makes symlink to only first depth in `castle/home`. If you want to link nested files/directories, please use .homesick_subdir.
84
85 For example, when you have castle like this:
86
87 castle/home
88 `-- .config
89 `-- fooapp
90 |-- config1
91 |-- config2
92 `-- config3
93
94 and have home like this:
95
96 $ tree -a
97 ~
98 |-- .config
99 | `-- barapp
100 | |-- config1
101 | |-- config2
102 | `-- config3
103 `-- .emacs.d
104 |-- elisp
105 `-- inits
106
107 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.
108
109 castle/.homesick_subdir
110
111 .config
112
113 and run `homesick link CASTLE`. The result is:
114
115 ~
116 |-- .config
117 | |-- barapp
118 | | |-- config1
119 | | |-- config2
120 | | `-- config3
121 | `-- fooapp -> castle/home/.config/fooapp
122 `-- .emacs.d
123 |-- elisp
124 `-- inits
125
126 Or `homesick track NESTED_FILE CASTLE` adds a line automatically. For example:
127
128 homesick track .emacs.d/elisp castle
129
130 castle/.homesick_subdir
131
132 .config
133 .emacs.d
134
135 home directory
136
137 ~
138 |-- .config
139 | |-- barapp
140 | | |-- config1
141 | | |-- config2
142 | | `-- config3
143 | `-- fooapp -> castle/home/.config/fooapp
144 `-- .emacs.d
145 |-- elisp -> castle/home/.emacs.d/elisp
146 `-- inits
147
148 and castle
149
150 castle/home
151 |-- .config
152 | `-- fooapp
153 | |-- config1
154 | |-- config2
155 | `-- config3
156 `-- .emacs.d
157 `-- elisp
158
159 ## Supported Ruby Versions
160
161 Homesick is tested on the following Ruby versions:
162
163 * 3.2
164 * 3.3
165 * 3.4
166
167 ## Note on Patches/Pull Requests
168
169 * Fork the project.
170 * Make your feature addition or bug fix.
171 * Add tests for it. This is important so it doesn't get broken unintentionally in a future version.
172 * Commit, but do not touch the rakefile, version, or history. (If you want your own version, that is fine — just bump the version in a separate commit that can be ignored when merging.)
173 * Open a pull request. Bonus points for topic branches.
174
175 ## Need homesick without the ruby dependency?
176
177 Check out [homeshick](https://github.com/andsens/homeshick).
178
179 ## Copyright
180
181 Copyright (c) 2010 Joshua Nichols. See LICENSE for details.