fresh

Keep your dot files fresh.

fresh is a tool to source shell configuration (aliases, functions, etc) from others into your own configuration files. We also support files such as ackrc and gitconfig. Think of it as Bundler for your dot files.

You can use fresh search to find fresh lines that have been added to the directory.

Contents

• Installation
• Usage
  • Sources
  • Shell files
  • Config files
  • Bin files
  • Locking to specific Git references
  • Filters
  • Option Blocks
  • Advanced Usage
• Command line options
• Maintainers
• Licence

Installation

Install fresh with the following:

bash -c "`curl -sL https://get.freshshell.com`"

This will:

• Create a ~/.fresh directory.
• Clone the latest version of fresh into ~/.fresh/source/freshshell/fresh.
• Create a ~/.freshrc file.

You will need to manually add source ~/.fresh/build/shell.sh to your shell config.

Manual steps

Don't want to run our shell script? The installation is simple:

git clone https://github.com/freshshell/fresh ~/.fresh/source/freshshell/fresh
echo "fresh freshshell/fresh bin/fresh --bin" >> ~/.freshrc
~/.fresh/source/freshshell/fresh/bin/fresh # run fresh
# Add `source ~/.fresh/build/shell.sh` to your shell config.

Usage

An example ~/.freshrc file:

# handles updating fresh
fresh freshshell/fresh bin/fresh --bin

# links your local ~/.dotfiles/gitconfig to ~/.gitconfig (you can change your local directory by setting $FRESH_LOCAL)
fresh gitconfig --file

# builds jasoncodes' aliases into ~/.fresh/build.sh
fresh jasoncodes/dotfiles shell/aliases/\*

# builds the shell/aliases/git.sh file into ~/.fresh/build/shell.sh
fresh twe4ked/dotfiles shell/aliases/git.sh

# links the config/ackrc file to ~/.ackrc
fresh twe4ked/dotfiles config/ackrc --file

# builds config/notmuch-config.erb with erb and links it to ~/.notmuch-config
fresh neersighted/dotfiles config/notmuch-config.erb --file=~/.notmuch-config --filter=erb

# links the gemdiff file to ~/bin/gem-diff
fresh jasoncodes/dotfiles bin/gemdiff --bin=~/bin/gem-diff

# builds the aliases/github.sh file locked to the specified git ref
fresh twe4ked/dotfiles aliases/github.sh --ref=bea8134

Running fresh will then build your shell configuration and create any relevant symbolic links.

Sources

Local files

If no remote source is specified (github_user/repo_name), fresh will look for local files relative to ~/.dotfiles/.

For example the following fresh line will look for ~/.dotfiles/shell/aliases/git.sh.

fresh shell/aliases/git.sh

GitHub repositories

To source from a GitHub repository you can specify the username and repo name separated with a slash:

fresh username/repo example.sh

Non-GitHub sources

You can also source from non-GitHub repositories by specifying the full git clone URL:

fresh git://example.com/path/to/repo.git example.sh

Shell files

With no options, fresh will join specified shell files together.

fresh twe4ked/dotfiles shell/aliases/git.sh
fresh jasoncodes/dotfiles shell/aliases/\*

Joins the shell/aliases/git.sh file from twe4ked/dotfiles with the shell/aliases/* files from jasoncodes/dotfiles into ~/.fresh/build/shell.sh.

Config files

fresh twe4ked/dotfiles config/ackrc --file
fresh example/dotfiles pry.rb --file=~/.pryrc

Links the config/ackrc file from twe4ked/dotfiles to ~/.ackrc and the pry.rb file from example/dotfiles to ~/.pryrc.

A single config file built from multiple sources

fresh jasoncodes/dotfiles config/tmux.conf --file
fresh twe4ked/dotfiles config/tmux.conf --file

Builds tmux configuration from both jasoncodes/dotfiles and twe4ked/dotfiles together into a single ~/.tmux.conf output.

Identifying source files in compiled output

Shell files automatically include comments before each section. To add annotations to config files you can use the --marker option:

fresh twe4ked/dotfiles 'vim/*' --file=~/.vimrc --marker='"'
fresh jasoncodes/dotfiles config/pryrc --file --marker

Ordering globbed directories

Using a glob to source multiple files from a single directory will read files in alphabetical order. If you need to control the order in which files are sourced, you can create a .fresh-order file in the directory being globbed containing an ordered list of files to read first.

Sourcing whole directories of files

Whole directories or repositories can be built and symlinked by including a trailing slash on the --file path:

fresh mutt --file=~/.mutt/
fresh tpope/vim-pathogen . --file=~/.vim/bundle/vim-pathogen/ # whole repository

Building files without symlinking

Some tools/libraries (e.g. zsh plugins) require specific directory structures. These can be built within the build directory (~/.fresh/build) by specifying a relative path on --file:

fresh zsh-users/zsh-syntax-highlighting zsh-syntax-highlighting.zsh --file=vendor/zsh-syntax-highlighting.zsh
fresh zsh-users/zsh-syntax-highlighting highlighters --file=vendor/highlighters/

These files can then be sourced from your main shell config with:

source ~/.fresh/build/vendor/zsh-syntax-highlighting.zsh

Bin files

fresh jasoncodes/dotfiles bin/sedmv --bin
fresh jasoncodes/dotfiles bin/gemdiff --bin=~/bin/gem-diff

Links the sedmv file from jasoncodes/dotfiles to ~/bin/sedmv and the gemdiff file from jasoncodes/dotfiles to ~/bin/gem-diff.

Locking to specific Git references

fresh twe4ked/dotfiles aliases/github.sh --ref=bea8134

Locks the aliases/github.sh file to the specified commit. You can use any Git reference: branches, commit hashes, tags, etc.

Filters

Filters allow you to run specified files through arbitrary commands at build time.

fresh neersighted/dotfiles config/muttrc.erb.asc --file=~/.muttrc --filter="gpg | erb"

Option Blocks

If you have a section of your ~/.freshrc file where multiple lines need the same options you can use fresh-options to reduce duplication.

# ~/.freshrc
fresh-options --file=~/.vimrc --marker=\"
  fresh twe4ked/dotfiles vim/vundle_before.vim
  fresh vim/vundle.vim
  fresh twe4ked/dotfiles vim/vundle_after.vim
  fresh vim/mappings.vim
fresh-options

fresh-options overrides any previous fresh-options calls. Passing no arguments resets back to the default.

Advanced Usage

There are many other ways you can customize fresh. Check out our advanced usage wiki pages for more information.

Command line options

Install

Running fresh or fresh install will build shell configuration and relevant symlinks.

Update

Running fresh update will update sources from GitHub repositories and run fresh install.

You can also optionally supply a GitHub username or username/repo:

fresh update jasoncodes       # update all jasoncodes' repos
fresh update twe4ked/dotfiles # update twe4ked's dotfiles

Local dotfiles

fresh update without any arguments will also fetch any changes made to your local dotfiles stored in ~/.dotfiles. You can update just your local dofiles by specifying the --local option.

Clean

When you remove a source from your ~/.freshrc or remove a --file/--bin line, you can use fresh clean to remove dead symlinks and source repos.

Search

You can search our fresh directory using fresh search. Feel free to add your own fresh lines to the wiki page!

Try:

fresh search twe4ked
fresh search jasoncodes
# or
fresh search ruby

Edit

Running fresh edit will open your ~/.freshrc in your default $EDITOR.

Show

fresh show will output each line of your ~/.freshrc along with every source file those lines match. Handy for auditing.

Subcommands

fresh will detect bin files that start with fresh- in your $PATH.

For example running fresh open is equivalent to running fresh-open.

Adding Lines Directly From The Command line

You can append fresh lines to your freshrc directly from the command line.

Try running:

fresh twe4ked/catacomb bin/catacomb --bin
# or
fresh https://github.com/twe4ked/catacomb/blob/master/bin/catacomb

You will then get a prompt comfirming that you wish to add the new line. You can then modify it if needed by running fresh edit.

Maintainers

fresh is maintained by jasoncodes and twe4ked.

Licence

MIT