andsens / homeshick

git dotfiles synchronizer written in bash

homeshick

In Unix, configuration files are king.
Tailoring tools to suit your needs through configuration can be empowering.
An immense number of hours is spent on getting these adjustments just right, but once you leave the confines of your own computer, these local optimizations are left behind.

By the power of git, homeshick enables you to bring the symphony of settings you have poured your heart into with you to remote computers. With it you can begin to focus even more energy on bettering your work environment since the benefits are reaped on whichever machine you are using.

However bare bones these machines are, provided that at least Bash 3 and Git 1.5 are available you can use homeshick. homeshick can handle multiple dotfile repositories. This means that you can install larger frameworks like oh-my-zsh or a multitude of emacs or vim plugins alongside your own customizations without clutter.

For detailed installation instructions, tutorials and tips & tricks have a look at the wiki.

Quick install

homeshick is installed to your own home directory and does not require root privileges to be installed.

git clone https://github.com/andsens/homeshick.git $HOME/.homesick/repos/homeshick

Note: If you'd like to help testing new features before they are released use git clone --branch testing https://...

To invoke homeshick, source the homeshick.sh script from your rc-script:

# from sh and its derivates (bash, dash, ksh, zsh etc.)
printf '\nsource "$HOME/.homesick/repos/homeshick/homeshick.sh"' >> $HOME/.bashrc
# csh and derivatives (i.e. tcsh)
printf '\nalias homeshick source "$HOME/.homesick/repos/homeshick/homeshick.csh"\n' >> $HOME/.cshrc
# fish shell
echo \n'source "$HOME/.homesick/repos/homeshick/homeshick.fish"' >> "$HOME/.config/fish/config.fish"

Contributing

Before submitting pull requests or reporting bugs, please make sure to read the contribution guidelines.

homeshick's Issues

Option to symlink files and not whole directories

homeshick seems to look at the first depth level of files (including directories) in the home/ directory of a castle and replace instances of those in the user's home/ directory by symlinks. However the castle files might only consist of a subset of the files that can be originally found in the user's directory and symlinking the directory wholesale would erase configuration files that the user might want to keep.

Ok, an example to make that clear :):

On linux a lot of configuration settings are stored in ~/.config/ . With the way symlinks are generated now we can't pick and choose the files to symlink in ~/.config/. homeshick attempts to replace the whole ~/.config/ directory, but this is problematic if we only want to sync sublime text settings for instance and not touch any of the other application settings.

One solution could be to only symlink files or maybe a prompt for partial symlinking.
I think this issue might be general enough to not just be "feature creep". Hopefully that was clear!

`homeshick check` misses unpushed changes

I did the following:

hook% homeshick track dotfiles .aliases.zsh .completion.zsh .correction.zsh .directories.zsh

But homeshick check reports:

hook% homeshick check
   up to date dotfiles
   up to date git
   up to date homeshick

Even though git status is:

hook% homeshick cd dotfiles
hook% git status
# On branch master
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#   new file:   .aliases.zsh
#   new file:   .completion.zsh
#   new file:   .correction.zsh
#   new file:   .directories.zsh
#
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#   modified:   .zshrc

Ignore .DS_Store in /home

If you browse a castle's /home folder (~/.homesick/repos/*/home) with finder, .DS_Store files are generated. I think it would be safe and smart for homeshick to ignore these files as I can't imagine anyone wanting to symlink them.

Thoughts? 🍰

Use xargs to parallelize

After introducing the default that operations are performed on all castles, xargs may be used to speed things up by checking remote changes etc. in parallel.

Document the hell out of the project

The README is a sorry excuse for a documentation.
Because this is no longer a simple replacement of homesick, homeshick needs its own documentation, explaining how everything works.

The basic premise will also need to be explained to the user.

Doesn't override symlinks even with -f flag.

ln prints errors that the symlinks already exist when using ~/.homeshick symlink -f dotfiles

Add deprecated message when invoking homeshick via $HOME/.homeshick

The original way of invoking homeshick was to alias $HOME/.homeshick.
The executable has since then been moved to bin/, and the old method of invoking it been kept intact via symlink.
We want to remove the home/ directory at some point, so there should be a depreciation message when invoking homeshick this way.

Documentation on installing more complex stuff (like spf13)

Hey. I'm not sure if this counts as an issue, and sorry if this belies mostly my own ineptitude, but could you add some documentation (maybe a wiki page?) on how to install odd packages like http://github.com/spf13/spf13-vim and https://github.com/sorin-ionescu/prezto, though I think prezto probably isn't too hard.

Also: the readme file link to the linking table wiki page is wrong.

Thanks for a lovely project, sorry this sort of thing probably belongs in a forum rather than a proper issue. Wasn't sure how else to ask. Thanks again.

Make homeshick output machine readable

Currently homeshick outputs text that is very readable by a human when viewed through a terminal. However, when read by or though anything else it becomes quite a challenge because carriage returns (\r) and coloring have to be taken into account.

homeshick should check whether STDOUT is the terminal and only then output data optimized for human viewing. This can easily be checked with [ -t 1].
This enhancement also makes unittests easier and allows for homeshick to be integrated with other code.

Can I use homeshick to manage files that are not in my ~ directory

Can I use homeshick to manage files that are not in my ~ directory? For example, my case is the "/Users/pitosalas/Library/Application Support/Sublime Text 3/Packages". It also contains a bunch of config files which I would like to see on my different machines.

I read and re-read the wiki and it seems to me that homeshick only likes managing files that live in by top level user directory. Any clarification here would be appreciated!

Auto-completion bug

When you navigate to some folder and you would like to track a new file:

$ cd  .config/some/path
$ homeshick track s[tab]

Here it could be nice, if the auto completion tries to auto complete the files in the current directory, but what does happen is, that the auto completer auto completes from the home folder.

Document switches

The only documentation of the commandline switches is in the help message.
They should also be documented in the wiki.

Get upstream remote instead of using "origin"

Both the list and check function use "origin" remote name to figure stuff out.
This should be the upstream remote instead.

Version control "Files outside your home directory"?

Regarding this section:

Wouldn't it make more sense for a links/ directory to be placed under version control?

Personally I'd place links/ under .homesick/repos/webapp/ (or whatever castle name) instead of under .homesick/.

Only allow switches where relevant

Currently one can specify the --skip, --force, --quiet and --batch switches before the subcommand and after the subcommand.
Unless the switch is truly global (e.g. --quiet), this shouldn't be possible.
This ties in very well with #60.

Can has untrack command

Pretty please!

Invoke homeshick via function instead of sourcing

Currently homeshick is invoked via alias homeshick="source \$HOME/.homesick/repos/homeshick/bin/homeshick.sh" (for an explanation as to why this is done, see #42).
This causes problems with the zsh completion script when aliases are set to be resolved before any completion is attempted.

Instead, homeshick should be invoked via a function call that is defined through .zshrc, this way the zsh completion actually works. Since bash and zsh share the same invocation script, we might as well use that approach for bash as well. The old way of invoking homeshick should be deprecated.

To keep things consistent, the same should be done for the .csh script.

Error determining git version

In the latest version, I get "error could not determine git version"

Wiki: cd .. ?

https://github.com/andsens/homeshick/wiki/Symlinking#repos-with-no-home-directory

homeshick cd dotfiles
cd ..
git submodule add https://github.com/gmarik/vundle.git home/.vim/bundle/vundle

Error:

~/.h/repos ❯❯❯ git submodule add https://github.com/gmarik/vundle.git home/.vim/bundle/vundle
fatal: Not a git repository (or any of the parent directories): .git

Use homeshick to update homeshick

By converting the homeshick repo into a castle and modifying the deployment script, homeshick can be updated by running homeshick pull homeshick

Documentation recommends unsafe installation method

recommending that someone download a script and pipe it into bash is one thing - they can read that before hand, at least. But recommending that they download it, and actively ignore the server certificate, while executing it, is really bad.

Avoid duplicate tracking

I accidentally added an already tracked file again using homeshick track. This moved the symlink from my homedir into the repo, which totally didn't make sense.

Maybe homeshick could check if a file is actually a symlink and then abort the homeshick track command.

Add cd command to enter castle

Add a homeshick cd CASTLE command so users can easily enter a castle and do git stuff.
Not sure whether pushd should be used instead though? This way users can write popd to get back to where they were.

spf13 github repo not found

Hi, thanks for a cool project. Trying to include the spf13 vim customization but the shorthand doesn't seem to work (maybe because of the hyphen?)

$ homeschick clone spf13/spf13-vim
        clone spf13/spf13-vim
        error Unable to clone spf13/spf13-vim. Git says:
fatal: repository 'spf13/spf13-vim' does not exist

Use -depth for find

Instead of using -mindepth 1 -maxdepth 1 we can use -depth 1 when looking for dotfiles.

Missing a "push" command

As far as I can see the current method for pushing updates is to manually cd into a repo and run git push from there.

I would prefer to be able to run "homeshick push [CASTLE]" instead.

Recursive Submodule Update

First off, thanks for the great package!

Secondly, at this point in the clone code it'd be helpful if you added the --recursive flag. Otherwise for nested submodules I have to go in and do this manually. And maybe also at line 53? (my bash-fu is not that great, so there may be other places I'm missing).

Thanks!

Make `--force` work with `homeshick clone`

Use case: Automated installs (should be idempotent, right?)

Expected: homeshick clone user/repo --force should not return non-zero exit when files exist. Why?

 Runtime options:
    ...
   -f, [--force]    # Overwrite files that already exist

Actual:

> $HOME/.homesick/repos/homeshick/bin/homeshick clone jrhorn424/dotfiles --batch --force
        clone https://github.com/jrhorn424/dotfiles.git
        error /home/deploy/.homesick/repos/dotfiles already exists

Same probably goes for --skip, in retrospect.

Only check for new files in home/

symlink_new_files checks for new files in the root of a castle. Since we only symlink stuff from home/ check that folder should suffice.

Don't symlink .git directories

I have submodules in my .vim/bundle folder. Might be nice to not waste time symlinking them all.

Autolinking feature

It would be nice if homeshick had a feature to autolink newly cloned repositories for automated, silent install on new boxes.

Unlink deleted files

Homeshick has a check which determines whether the user should be asked about symlinking newly added files.

Similarly we could add an unlink command which removes symlinks to deleted files.

Implement update check

A feature like the one oh-my-zsh has about auto-updating could be implemented without using any timestamp files by checking FETCH_HEAD in the git dirs with:

stat -c %Y $repo/.git/FETCH_HEAD

As suggested in http://stackoverflow.com/a/9229377/339505

Unit test multiple parameters

Currently the unit tests only execute homeshick with a single castle or file parameter.
The tests should also check if multiple parameters only implicit ones work (like homeshick pull which pulls all castles).

Implement exit codes

homeshick should implement some meaningful exit codes so that other tools can get some info from it and automate things (e.g. homesick check exits with 0 when all is up to date and !=0 when the server is ahead or behind)

Inconsistency on "Symlinking" wiki page.

Under Shallow symlinking, .emacs.d is inconsistent with .emacs/.

Under Files outside your home directory, /var/www is inconsistent with var-www.

Cannot track files with characters that needs escaping

$ homeshick track rc-files Library/Application\ Support/Sublime\ Text\ 3/Packages/User/Default\ \(OSX\).sublime-keymap 
      symlink /Users/khs/.homesick/repos/rc-files/home/Library/Application to /Users/khs/Library/Application
        error The file /Users/khs/Library/Application does not exist.

Add tab completion directions to readme

The tutorial section of the readme should include a note about the bash-completions:

source ~/.homesick/repos/homeshick/completions/homeshick-completion.bash

Convert README into wiki

The README is getting to large, convert it into a wiki and multiple pages.
Some of the most important stuff should however stay in the README.

Use POSIX syntax for help menu

The help message is currently thrown together with no overall structure.
POSIX actually has a standard for how this should be structured, it should be used.

Error with Git 1.8.2.1

It seems homeshick has problems parsing my Git version (1.8.2.1), because when I run it to clone my dotfiles repo I get the following error:

expr: not a decimal number: '1'

Running homeshick with the -x bash option, I see the following (just the relevant snippet):

+ local git_out
++ version_compare 1.8.2. 1.6.5
++ expr '(' 1.8.2. : '\([^.]*\)' ')' - '(' 1.6.5 : '\([^.]*\)' ')' '|' '(' 1.8.2..0 : '[^.]*[.]\([^.]*\)' ')' - '(' 1.6.5.0 : '[^.]*[.]\([^.]*\)' ')' '|' '(' 1.8.2..0.0 : '[^.]*[.][^.]*[.]\([^.]*\)' ')' - '(' 1.6.5.0.0 : '[^.]*[.][^.]*[.]\([^.]*\)' ')' '|' '(' 1.8.2..0.0.0 : '[^.]*[.][^.]*[.][^.]*[.]\([^.]*\)' ')' - '(' 1.6.5.0.0.0 : '[^.]*[.][^.]*[.][^.]*[.]\([^.]*\)' ')'
expr: not a decimal number: '1'

Add directory symlink explanation to documentation

As mentioned in issue #19, the documentation should explain how one can avoid deep symlinking of a directory.

Document test framework

The test runner has the --help switch and can take testsuites as arguments, this should be documented somewhere, otherwise it's not really of any use.

It should also be pointed out that the testrunner requires virtually no setup.

"updates" is not a true alias of check

check takes castles as parameters while updates always checks all castles.
Make updates accept castle params as well.

Make track work with directories

Instead of disallowing directory tracking actually move the folder and then proceed like symlink does. Maybe the code in the symlink iteration should be refactored to be used both places.

`check` should check for dirty working copy

It should be possible to see whether the working copy of a castle is dirty by running check.

Why tracking only caslte in $HOME ?

Hi,

I don't understand why you are forbid file tracking from outside of $HOME.

$ homeshick track profile.d /etc/profile.d/bash_completion.sh
error The file /etc/profile.d/bash_completion.sh must be in your home directory.

I think there is a good reason, but I'don't understand this point.

Without this limitation homeshick would be a great tool for backing up system config files dispersed in different directories.

Git is loud

git is extremely noisy when cloning and pulling, --quiet seems to have only little effect.
Simply redirecting both stdout and stderr to /dev/null is not an option since we want git to tell the user what went wrong in case of an error.

Unit test spaces in parameters

Parameter passing has been played a little loose and fast. The first issue with that came with #67. The unit tests should try provoking errors with spaces in pathnames, castlenames and even function call return values.

Bad links in wiki.

https://github.com/andsens/homeshick/wiki/Symlinking

"Flat symlinking" points to:

https://github.com/andsens/homeshick/wiki/Symlinking#flat-symlinking

It should probably be:

[Shallow symlinking](https://github.com/andsens/homeshick/wiki/Symlinking#shallow-symlinking)

There's multiple references to this bad #hash throughout the page and in other parts of the wiki.