This is probably already set in your ENV. dotbare uses this variable to determine
This is probably already set in your ENV. `dotbare` uses this variable to determine
which editor to use when running `dotbare fedit`.
```sh
# Default
# Default value
export EDITOR="vim"
```
### DOTBARE_KEY
This variable set default keybinds for fzf in dotbare. You could checkout a list of keybinds
This variable set default keybinds for fzf in `dotbare`. You could checkout a list of keybinds
to set [here](https://github.com/junegunn/fzf/blob/97a725fbd0e54cbc07e4d72661ea2bd2bb7c01c1/man/man1/fzf.1#L648).
```sh
# Default
# Default value
export DOTBARE_KEY="
--bind=alt-a:toggle-all # toggle all selection
--bind=alt-j:jump # label jump mode, sort of like vim-easymotion
@ -399,232 +357,50 @@ Customize fzf settings for dotbare. This is useful when you want a different
fzf behavior from your normal system fzf settings.
```sh
# Default is unset
# By default this variable is not set
# More settings checkout fzf man page and their wiki
```
## Commands
### DOTBARE_PREVIEW
> dotbare doesn't have a man page yet (it is planned tho), for help, type dotbare [COMMAND] -h
### Checkout all available scripts and their help manual
This variable determines the preview command for file previews. By default, the preview is automatically determined
using fall back (bat -> highlight -> coderay -> rougify -> cat). Set this variable to control the preview command if
you have a specific preference or if you want extra flags/settings. Reference [here](https://github.com/kazhala/dotbare/blob/master/helper/preview.sh).
```sh
# run dotbare without any arguments will display all available `f` scripts
dotbare
# or checkout help for dotbare
dotbare -h
dotbare --help
# for normal git help
dotbare help
# By default this value is not set, dotbare uses a fall back method to determine which command to use.
# Make sure to have "{}" included when customizing it, the preview script substitute "{}" for actual filename.
export DOTBARE_PREVIEW="cat -n {}"
```
### fedit
Select files/commits through fzf and edit selected files/commits in \$EDITOR.
Editing commits will perform a interactive rebase.
- Default: list all tracked files and open \$EDITOR to edit the selected files. Support multi selection.
- `-h, --help`: show the help message of `dotbare fedit` and exit.
- `-m, --modified`: list all modified files and open \$EDITOR to edit the selected files. Support multi selection.
- `-c, --commit`: list all commits and edit the selected commit through interactive rebase.
Select files/directories or modified files through fzf and stage the selected files/directories.
- Default: list all modified files and stage selected files. Support multi selection.
- `-h, --help`: show the help message of `dotbare fadd` and exit.
- `-f, --file`: list all files in current directory and stage selected files. Support multi selection. (Used for staging new files to index).
- `-d, --dir`: list all directory under current directory and stage selected directory. Support multi selection. (Used for staging new files to index).
Backup files to \$DOTBARE_BACKUP directory. This is particular useful when untracking files
or migrating to new machines. This is used by `dotbare finit -u [URL]` for backing up conflicted checkout files.
- Default: backup all tracked files to \$DOTBARE_BACKUP directory. (Default: use `cp` command).
- `-h, --help`: show the help message of `dotbare fbackup` and exit.
- `-s, --select`: list all tracked files and only backup the selected files. Support multi selection.
- `-p PATH, --path PATH`: specify path to files to backup. (This is mainly used by `dotbare finit -u [URL]`).
- `-m, --move`: use `mv` instead of the default `cp` command to backup. (This is mainly used by `dotbare finit -u [URL]`).
### fstat
Display interactive git status menu. Toggle file stage/unstage status interactively.
### DOTBARE_DIFF_PAGER
- `-h, --help`: show the help message of `dotbare fstat` and exit.
This variable controls the diff output pager in previews like `dotbare flog`, `dotbare fadd` etc. It will read the value
of `git config core.pager` to determine the pager to use. If you have a specific preference for `dotbare` or have not set
the global pager, you could use this variable to customize the diff preview.
### finit
Initialise dotbare with a bare repository or add -u [URL] flag for migrating existing dotfiles from
remote git repo to current system.
Note: do not use this command if you are using symlink/GNU stow and want to keep your current setup.
- Default: init the bare repository at \$DOTBARE_DIR.
- `-h, --help`: show the help message of `dotbare finit` and exit.
- `-u URL, --url URL`: migrate existing dotfiles from remote git repo to current system.
- `-s, --submodule`: if you have defined submodules in your bare repo (i.e. containes .gitmodule), add -s
flag to clone submodules as well during migration.
- `-y, --yes`: acknowledge all actions that will be taken and skip confirmation.
### funtrack
Stop tracking the selected git files. It could also be used to temporarily stop tracking changes
for files and then later on resume tracking changes.
**Note: This command has severe limitations.**
By default, selected files are permanently untracked from git. Selected files will be
remove from index while keeping the file in your current system. However, when your other
machines pull down the changes, the untracked files will be deleted by git. This is a limitation
with git, to overcome this, after untracking the files, run `dotbare fbackup` to backup all files on
other machines before pulling down the changesto avoid any file loss.
After pulling new changes, move the deleted files from backup back to their original position.
More discussions [here](https://stackoverflow.com/questions/1274057/how-to-make-git-forget-about-a-file-that-was-tracked-but-is-now-in-gitignore).
`dotbare funtrack` does come with capabilities to temporarily untrack files, which will not
remove the untracked files from other system. However, this is **NOT** recommended
way to untrack files, explained [here](https://www.git-scm.com/docs/git-update-index#_notes).
- Default: list all tracked files and permanently untrack the selected files. Support multi selection.
- `-h, --help`: show the help message of `dotbare funtrack` and exit.
- `-t, --temp`: list all tracked files and temporarily untrack changes of the selected files. Support multi selection.
- `-r, --resume`: list all tracked files and resume tracking changes of the selected files.
- `-y, --yes`: acknowledge all actions that will be taken and skip confirmation.
### fupgrade
Update dotbare to the latest master. It will perform a `git pull --rebase --stat` and also
performing a auto-stash if needed (copied the method from OMZ). This is useful if you are not
using a plugin manager.
- `-h, --help`: show the help message of `dotbare fstat` and exit.
## Custom scripts
`dotbare` may not contains all the functionalities of your need, feel free to open up feature request. You could also
define your custom scripts under the scripts folder in `dotbare`. The `.gitignore` are configured to ignore everything except the scripts used by `dotbare` default,
so you can name your scripts any name you want. You can then track your custom scripts using `dotbare` to ensure the scripts are available in all of your machines.
Feel free to open pull request for your script, I'm happy to review and discuss for merging.
A dedicated wiki page will be setup to document API for helper functions.
## Tips and Tricks
- Most commands related to files support multi selection (default fzf setting is TAB for multi select).
- Most commands related to commits and branches doesn't support multi selection.
- `dotbare` has disabled the command `dotbare add --All` as it is a really dangerous command in the conext of `dotbare` as it will stage everything in your \$DOTBARE_TREE to the index.
## Usage
```sh
# Recommended ways
dotbare fadd # and then press alt-a to select all
dotbare add -u # stage all modified file to index
dotbare commit -am "message" # this also works, it will stage all modified files and then commit
```
A full list of `dotbare` commands and their usage are documented in **[wiki](https://github.com/kazhala/dotbare/wiki/Commands)**.
- Add the value of `$DOTBARE_DIR` to global .gitignore to avoid any weird recursion problem if accidentally adding
`$DOTBARE_DIR` to index, the value needs to be relative path to `$DOTBARE_TREE`
## Custom Scripts
```sh
# e.g. DOTBARE_DIR="$HOME/.cfg", DOTBARE_TREE="$HOME"
echo ".cfg" >> $HOME/.gitignore
# e.g. DOTBARE_DIR="$HOME/.config/.cfg" DOTBARE_TREE="$HOME"
echo ".config/.cfg" >> $HOME/.gitignore
# e.g. DOTBARE_DIR="$HOME/.config/.cfg" DOTBARE_TREE="$HOME/.config"
echo ".cfg" >> $HOME/.gitignore
```
Detailed explanation of how to create custom scripts and the API of `dotbare` helper functions
is documented over in **[wiki](https://github.com/kazhala/dotbare/wiki/Custom-Scripts)**.
- Define a custom vim command to select dotfiles using [fzf.vim](https://github.com/junegunn/fzf.vim)
Latest changes are documented in CHANGELOG.md. View the upcoming changes in the [CHANGELOG](https://github.com/kazhala/dotbare/blob/dev/CHANGELOG.md) of dev branch.
## Testing
`dotbare` is unit tested using [bats](https://github.com/bats-core/bats-core). A very weird mock tests are implemented using PATH override method.
This will be improved later and documented in a dedicated README in tests folder for more readability and extensibility.
`dotbare` is unit tested using [bats](https://github.com/bats-core/bats-core). Mock tests are implemented using PATH override method.
This documented in a dedicated README in tests folder for more readability and extensibility.
Not all functions have 100% coverage and lots of user interaction cannot be effectively tested, please fire up issues if something went wrong.
@ -653,7 +429,7 @@ Leave a star :)
## Background
dotbare was initially part of my personal scripts, I had a hard time sharing those scripts
`dotbare` was initially part of my personal scripts, I had a hard time sharing those scripts
and as the number of scripts grows, I feel like is more appropriate to make a dedicated project
for it. I hope you find it useful and enjoy it, thanks!
@ -667,5 +443,5 @@ for it. I hope you find it useful and enjoy it, thanks!
## Demo
You could find some more gif demo [here](https://github.com/kazhala/dotbare/issues/1)
You could find some more demo [here](https://github.com/kazhala/dotbare/issues/1)
Kevin Zhuang
4 years ago