Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/freshshell/fresh

Keep your dotfiles fresh.
https://github.com/freshshell/fresh

dotfiles fresh freshrc

Last synced: 25 days ago
JSON representation

Keep your dotfiles fresh.

Awesome Lists containing this project

README 

        
# 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].



[![Build Status](https://travis-ci.com/freshshell/fresh.svg?branch=master)](https://travis-ci.com/freshshell/fresh)



## Contents



- [Installation](#installation)

- [Usage](#usage)

	- [Sources](#sources)

	- [Shell files](#shell-files)

	- [Config files](#config-files)

	- [Bin files](#bin-files)

	- [Locking to specific Git references](#locking-to-specific-git-references)

	- [Filters](#filters)

	- [Option Blocks](#option-blocks)

	- [Advanced Usage](#advanced-usage)

- [Command line options](#command-line-options)

- [Maintainers](#maintainers)

- [Licence](#licence)



## Installation



Install [fresh](http://freshshell.com/) with the following:



``` sh

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:



``` sh

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:



``` sh

# 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/shell.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`.



``` 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:



``` sh

fresh username/repo example.sh

```



#### Non-GitHub sources



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



``` sh

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

```



### Shell files



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



``` sh

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



``` sh

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



``` sh

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:



``` sh

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:



``` sh

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`:



``` sh

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:



``` sh

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

```



### Bin files



``` sh

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



``` sh

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][filters] allow you to run specified files through arbitrary commands at build time.



``` sh

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

```



[filters]: https://github.com/freshshell/fresh/wiki/Filters



### 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.



``` sh

# ~/.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][advanced usage] for more information.



[advanced usage]: https://github.com/freshshell/fresh/wiki#advanced-usage



## 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:



``` sh

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][directory] using `fresh search`.

Feel free to add your own fresh lines to the wiki page!



Try:



``` sh

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:



``` sh

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



[jasoncodes/dotfiles]: https://github.com/jasoncodes/dotfiles

[twe4ked/dotfiles]: https://github.com/twe4ked/dotfiles

[jasoncodes]: https://github.com/jasoncodes

[twe4ked]: https://github.com/twe4ked

[directory]: https://github.com/freshshell/fresh/wiki/Directory