Archives/dotbare
2
0
Fork 0
mirror of https://github.com/kazhala/dotbare synced 2024-11-04 06:00:45 +00:00
Code Issues Projects Releases Wiki Activity

docs(readme): update command flags and updating wording

Browse Source
This commit is contained in:
kevin zhuang 2020-06-30 23:18:46 +10:00
parent d8f98b099e
commit f9abb31041
13 changed files with 217 additions and 171 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG.md
View File

@ -2,7 +2,7 @@
Noteble changes are documentated in this file. Noteble changes are documentated in this file.
## 2.0.0 ## 1.2.0
### Added ### Added

248
README.md
View File

@ -8,8 +8,8 @@
## Introduction ## Introduction
dotbare is a command line utility to help you manage your dotfiles. It wraps around git bare dotbare is a command line utility to help you manage your dotfiles. It wraps around git bare
repository and heavily utilise [fzf](https://github.com/junegunn/fzf) for better user experience. repository and heavily utilises [fzf](https://github.com/junegunn/fzf) for an interactive experience.
It is inspired by [forgit](https://github.com/wfxr/forgit), a git wrapper that utilise fzf for interactive experience. It is inspired by [forgit](https://github.com/wfxr/forgit), a git wrapper using fzf.
dotbare uses a different implementation approach and focuses on managing and interacting with your dotfiles. dotbare uses a different implementation approach and focuses on managing and interacting with your dotfiles.
Don't worry about migration if you have a symlink/GNU stow setup, you can easily integrate dotbare with them. Don't worry about migration if you have a symlink/GNU stow setup, you can easily integrate dotbare with them.
@ -20,19 +20,19 @@ Pros:
- Customizable - Customizable
- Easy migration - Easy migration
- Flat learning curve - Flat learning curve
- Manage dotfiles in any directory - Manage dotfiles anywhere in your system
- Integration with symlink/GNU stow setup - Integration with symlink/GNU stow setup
You could find out how git bare repository could be used for managing dotfiles [here](https://www.atlassian.com/git/tutorials/dotfiles). You could find out how git bare repository could be used for managing dotfiles [here](https://www.atlassian.com/git/tutorials/dotfiles).
Or a [video](https://www.youtube.com/watch?v=tBoLDpTWVOM&t=288s) explanation that helped me to get started. If you currently Or a [video](https://www.youtube.com/watch?v=tBoLDpTWVOM&t=288s) explanation that helped me to get started. If you are currently
is using symlink/GNU stow setup, checkout how to integrate dotbare with them [here](#migrating-from-a-generic-symlink-setup-or-gnu-stow). using a symlink/GNU stow setup, checkout how to integrate dotbare with them [here](#migrating-from-a-generic-symlink-setup-or-gnu-stow).
![Demo](https://user-images.githubusercontent.com/43941510/82142379-4a1e7500-987f-11ea-8d35-8588a413efd3.png) ![Demo](https://user-images.githubusercontent.com/43941510/82142379-4a1e7500-987f-11ea-8d35-8588a413efd3.png)
## Why ## Why
It has always been a struggle for me to get started with managing dotfiles using version control, It has always been a struggle for me to get started with managing dotfiles using version control,
as some other tools like "GNU stow" really scares me off with all the symlinks, until I found as some tools like "GNU stow" really scares me off with all the symlinks, until I found
out about using git bare repository for managing dotfiles, zero symlinks, minimal setup out about using git bare repository for managing dotfiles, zero symlinks, minimal setup
required and you keep your dotfiles at the location they should be. required and you keep your dotfiles at the location they should be.
@ -80,6 +80,7 @@ with minimal set up required.
- [finit: initialise/migrating dotbare](#finit) - [finit: initialise/migrating dotbare](#finit)
- [funtrack: untrack files](#funtrack) - [funtrack: untrack files](#funtrack)
- [fupgrade: update dotbare](#fupgrade) - [fupgrade: update dotbare](#fupgrade)
- [Custom scripts](#custom-scripts)
- [Tips and Tricks](#tips-and-tricks) - [Tips and Tricks](#tips-and-tricks)
- [Testing](#testing) - [Testing](#testing)
- [Contributing](#contributing) - [Contributing](#contributing)
@ -92,7 +93,7 @@ with minimal set up required.
### zsh ### zsh
dotbare should work with any zsh plugin manager, below is only demonstration dotbare should work with any zsh plugin manager, below is only demonstration.
#### zinit #### zinit
@ -138,7 +139,7 @@ antigen bundle kazhala/dotbare
dotbare comes with a `dotbare.plugin.bash` which will enable both bash command line dotbare comes with a `dotbare.plugin.bash` which will enable both bash command line
completion for dotbare commands and adding dotbare to your PATH. If you don't want the completion, completion for dotbare commands and adding dotbare to your PATH. If you don't want the completion,
simply follow the instructions in [others](#others) and add dotbare to your PATH. follow the instructions in [others](#others) which simply add dotbare to your PATH.
- Clone the repository (change ~/.dotbare to the location of your preference) - Clone the repository (change ~/.dotbare to the location of your preference)
@ -179,8 +180,11 @@ simply follow the instructions in [others](#others) and add dotbare to your PATH
### Dependencies ### Dependencies
- Required dependency - Required dependency
- git
- [fzf](https://github.com/junegunn/fzf) - [fzf](https://github.com/junegunn/fzf)
- bash(You don't need to run bash, but dotbare does require you have bash in your system) - bash(You don't need to run bash, but dotbare does require you have bash in your system)
- Optional dependency - Optional dependency
- [tree](https://linux.die.net/man/1/tree) (Will provide a directory tree view when finding directory) - [tree](https://linux.die.net/man/1/tree) (Will provide a directory tree view when finding directory)
@ -194,7 +198,7 @@ simply follow the instructions in [others](#others) and add dotbare to your PATH
1. init git bare repository 1. init git bare repository
Note: by default, `dotbare finit` will set up a bare repo in \$HOME/.cfg, to customize Note: by default, `dotbare finit` will set up a bare repository in \$HOME/.cfg, to customize
location and various other settings, checkout [customization](#customization) location and various other settings, checkout [customization](#customization)
```sh ```sh
@ -203,9 +207,9 @@ simply follow the instructions in [others](#others) and add dotbare to your PATH
2. add dotfiles you want to track 2. add dotfiles you want to track
```sh Treat dotbare as normal `git` commands.
# Treat dotbare as normal `git` commands.
```sh
dotbare fadd -f dotbare fadd -f
# or # or
dotbare add [FIELNAME] dotbare add [FIELNAME]
@ -243,7 +247,7 @@ simply follow the instructions in [others](#others) and add dotbare to your PATH
export DOTBARE_TREE="$HOME" export DOTBARE_TREE="$HOME"
``` ```
4. remove the original alias and use dotbare the same except with _super power_ 4. remove the original alias and use `dotbare`
5. optionally you could alias config to dotbare so you keep your muscle memory 5. optionally you could alias config to dotbare so you keep your muscle memory
@ -253,10 +257,6 @@ simply follow the instructions in [others](#others) and add dotbare to your PATH
#### Migrating from a generic symlink setup or GNU stow #### Migrating from a generic symlink setup or GNU stow
> If you already have a symlink setup either custom or with GNU stow.
> You could either integrate dotbare with your current set up or
> do a complete migration.
##### Keep your current setup but integrate dotbare ##### Keep your current setup but integrate dotbare
1. follow the steps in [install](#install) to install dotbare 1. follow the steps in [install](#install) to install dotbare
@ -276,21 +276,27 @@ simply follow the instructions in [others](#others) and add dotbare to your PATH
##### Complete migration ##### Complete migration
I haven't used GNU stow or any symlink setup, but I do recommend keep your current setup **NOTE**: There's an open [issue](https://github.com/kazhala/dotbare/issues/12) where if you have more than 100 dotfiles
and integrate with dotbare. If you are really happy with `dotbare`, as long as your remote tracked, this method would cause a crash during migration. Please don't use this method before the issue get resolved.
repository resembles the structure of your home holder (reference what I mean in my [repo](https://github.com/kazhala/dotfiles.git)),
simply run the command below. While bare method is great and easy, I recommend keeping your current GNU stow/symlink setup and integrate it with dotbare instead of a migration.
If you are really happy with `dotbare`, as long as your remote repository resembles the structure of your home holder
(reference what I mean in my [repo](https://github.com/kazhala/dotfiles.git)), simply run the command below.
**Disclaimer**: I have not done nearly enough test on this as I don't personally use GNU stow or symlink setup, migrate this way with caution.
I recommend you test this migration in docker, see [Test-it-in-docker](#test-it-in-docker).
```sh ```sh
# Disclaimer: I have not test this with GNU stow, migrate in this way with caution. # dotbare will replace all symlinks with the original file and a bare repository will be created at $DOTBARE_DIR
# I recommend you test this migration in docker, see #Test-it-in-docker
dotbare finit -u [URL] dotbare finit -u [URL]
``` ```
#### Migrating dotbare to a new system #### Migrating dotbare to a new system
1. follow the steps in [install](#install) to install dotbare 1. follow the steps in [install](#install) to install dotbare
2. Optionally set env variable to customize dotbare location. Checkout [customization](#customization) 2. Optionally set env variable to customize dotbare location
> Checkout [customization](#customization)
```sh ```sh
export DOTBARE_DIR="$HOME/.cfg" export DOTBARE_DIR="$HOME/.cfg"
@ -305,8 +311,8 @@ dotbare finit -u [URL]
#### Test it in docker #### Test it in docker
I strongly suggest you give dotbare a try in docker, especially When you are about to do migrations, I strongly suggest you give the migration a try in docker first.
when it comes to first time migration. The dotbare image is based on alpine linux.
```sh ```sh
docker pull kazhala/dotbare:latest docker pull kazhala/dotbare:latest
@ -327,8 +333,8 @@ This is the location of the bare repository, dotbare will look for this director
and query git information or it will create this directory when initializing dotbare. and query git information or it will create this directory when initializing dotbare.
Change this to location or rename the directory to your liking. Change this to location or rename the directory to your liking.
If you are using symlink/GNU stow setup, set this variable point to your .git folder If you are using symlink/GNU stow setup, set this variable point to the .git folder
in your working directory of your dotfiles. within your dotfile directory.
```sh ```sh
# Default # Default
@ -340,7 +346,7 @@ DOTBARE_DIR="$HOME/.cfg"
This is the working tree for the git bare repository, meaning this is where the version This is the working tree for the git bare repository, meaning this is where the version
control will take place. I don't recommend changing this one unless **ALL** of your config control will take place. I don't recommend changing this one unless **ALL** of your config
file is in something like \$XDG_CONFIG_HOME or if you are using symlink/GNU stow setup, file is in something like \$XDG_CONFIG_HOME or if you are using symlink/GNU stow setup,
set this variable to point to the folder contains your actual dotfiles. set this variable to point to the folder containing your dotfiles.
```sh ```sh
# Default # Default
@ -352,8 +358,7 @@ DOTBARE_TREE="$HOME"
This variable is used to determine where to store the backup of your files. It is used This variable is used to determine where to store the backup of your files. It is used
mainly by `dotbare fbackup` which will back up all of your tracked dotfiles into this location. mainly by `dotbare fbackup` which will back up all of your tracked dotfiles into this location.
It is also used by `dotbare finit -u [URL]`, when there is checkout conflict, dotbare will It is also used by `dotbare finit -u [URL]`, when there is checkout conflict, dotbare will
automatically backup conflicted files to this location. You probably shouldn't change this automatically backup conflicted files to this location.
location.
```sh ```sh
# Default # Default
@ -381,7 +386,7 @@ to set [here](https://github.com/junegunn/fzf/blob/97a725fbd0e54cbc07e4d72661ea2
# Default # Default
DOTBARE_KEY=" DOTBARE_KEY="
--bind=alt-a:toggle-all # toggle all selection --bind=alt-a:toggle-all # toggle all selection
--bind=alt-j:jump # label jump mode, sort of like easymotion --bind=alt-j:jump # label jump mode, sort of like vim-easymotion
--bind=alt-0:top # set cursor back to top --bind=alt-0:top # set cursor back to top
--bind=alt-s:toggle-sort # toggle sorting --bind=alt-s:toggle-sort # toggle sorting
--bind=alt-t:toggle-preview # toggle preview --bind=alt-t:toggle-preview # toggle preview
@ -396,80 +401,86 @@ fzf behavior from your normal system fzf settings.
```sh ```sh
# Default is unset # Default is unset
# More settings checkout fzf man page and their wiki # More settings checkout fzf man page and their wiki
# You could also take a look at my fzf config
# https://github.com/kazhala/dotfiles/blob/5507a2dea4f4a420e6d65a423abaa247521f89a8/.zshrc#L56
``` ```
## Commands ## Commands
> dotbare doesn't have a man page yet, will come later, for help, type dotbare [COMMAND] -h > 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 ### Checkout all available scripts and their help manual
```sh ```sh
# run dotbare without any arguments # run dotbare without any arguments will display all available `f` scripts
dotbare dotbare
# or checkout help for dotbare # or checkout help for dotbare
dotbare -h dotbare -h
dotbare help
# for normal git help
dotbare --help dotbare --help
# for normal git help
dotbare help
``` ```
### fedit ### fedit
List all tracked dotfiles and edit the selected file through \$EDITOR, it also support Select files/commits through fzf and edit selected files/commits in \$EDITOR.
edit commits through interactive rebase. Editing commits will perform a interactive rebase.
- Default: list all tracked files and open \$EDITOR to edit it. Support multi selection. - Default: list all tracked files and open \$EDITOR to edit the selected files. Support multi selection.
- -m: list all modified files and open \$EDITOR to edit it. Support multi selection. - `-h, --help`: show the help message of `dotbare fedit` and exit.
- -c: list all commits and open interactive rebase to edit commits. - `-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.
![fedit](https://user-images.githubusercontent.com/43941510/82388905-0d6c9c80-9a7e-11ea-845f-21338c2d3a1f.png) ![fedit](https://user-images.githubusercontent.com/43941510/82388905-0d6c9c80-9a7e-11ea-845f-21338c2d3a1f.png)
### fadd ### fadd
Stage modified files, stage new file or directory interactive by through fzf. 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. - Default: list all modified files and stage selected files. Support multi selection.
- `-f, --file`: list all files in current directory and stage selected files. Support multi selection. (Used for staging new files to index) - `-h, --help`: show the help message of `dotbare fadd` and exit.
- `-d, --dir`: list all directory under current directory and stage selected directory. Support multi selection. (Used for staging new files to index) - `-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).
![fadd demo](https://user-images.githubusercontent.com/43941510/82388994-4e64b100-9a7e-11ea-953a-621d85347c57.png) ![fadd demo](https://user-images.githubusercontent.com/43941510/82388994-4e64b100-9a7e-11ea-953a-621d85347c57.png)
### freset ### freset
Reset/unstage file, reset HEAD back to certain commits and reset certain file back to certain Select staged files or commits through fzf and then reset(unstage) staged files or reset HEAD back to certain commits.
commits. Also supports reset HEAD back to certain commits either `--soft`, `--hard`, `--mixed`, as well Also supports reset HEAD back to certain commits using either `--soft`, `--hard`, `--mixed` flags.
as reset a file back to certain commits. More information on differences [here](https://git-scm.com/docs/git-reset#Documentation/git-reset.txt-emgitresetemltmodegtltcommitgt). More information on differences between flags [here](https://git-scm.com/docs/git-reset#Documentation/git-reset.txt-emgitresetemltmodegtltcommitgt).
- Default: list all staged files and unstage the selected files. Support multi selection. - Default: list all staged files and unstage the selected files. Support multi selection.
- `-c, --commit`: list all commits and then reset HEAD back to the selected commits. (Default: `--mixed`, put all changes into modified state) - `-h, --help`: show the help message of `dotbare freset` and exit.
- `-S, --soft`: use `--soft` flag instead of `--mixed` flag, reset HEAD to certain commit without modify working tree. - `-c, --commit`: list all commits and then reset HEAD back to the selected commits. (Default: `--mixed`, put all changes into modified state).
- `-S, --soft`: use `--soft` flag instead of `--mixed` flag, reset HEAD to certain commit without modifying working tree.
- `-H, --hard`: use `--hard` flag instead of `--mixed` flag, reset HEAD to certain commit discard all changes from the working tree. - `-H, --hard`: use `--hard` flag instead of `--mixed` flag, reset HEAD to certain commit discard all changes from the working tree.
- `-y, --yes`: acknowledge all actions that will be taken and skip confirmation.
### fcheckout ### fcheckout
Checkout files/commit/branch interactively. Checkout files/commit/branch interactively through fzf.
- Default: list all modified files and reset selected files back to HEAD. Support multi selection. (Discard all changes) - Default: list all modified files and reset selected files back to HEAD. Support multi selection. (Discard all changes)
Note: if your file is staged, you will need to unstage first before running fcheckout to make it work. **Note**: if your file is staged, you will need to unstage first before running fcheckout to make it work.
- -a: list all tracked files and then prompt commit selection, checkout selected file in the version of selected commit. - `-h, --help`: show the help message of `dotbare fcheckout` and exit.
- -b: list all branch and switch to selected branch. - `-s, --select`: list all tracked files and select a commit to checkout the selected files. Support multi selection.
- -c: list all commits and checkout selected commit. - `-b, --branch`: list all branch and switch/checkout the selected branch.
- `-c, --commit`: list all commits and checkout selected commit.
- `-y, --yes`: acknowledge all actions that will be taken and skip confirmation.
![fcheckout demo](https://user-images.githubusercontent.com/43941510/82389569-e2834800-9a7f-11ea-92b5-ed20c8f2ecda.png) ![fcheckout demo](https://user-images.githubusercontent.com/43941510/82389569-e2834800-9a7f-11ea-92b5-ed20c8f2ecda.png)
### flog ### flog
Interactive log viewer that will prompt you with a menu after selecting a commit. Allows Interactive log viewer that will prompt you with a menu after selecting a commit. The action menu contains options including
edit, reset, revert and checkout the selected commits. edit, reset, revert and checkout the selected commits.
- Default: list all commits and then prompt menu to select actions. - Default: list all commits and then prompt menu to select action to perform.
- -r: revert the selected commit - `-h, --help`: show the help message of `dotbare flog` and exit.
- -R: reset HEAD back to the selected commit - `-r, --revert`: revert the selected commit and skip action menu.
- -e: edit selected commit through interactive rebase - `-R, --reset`: reset HEAD back to the selected commit and skip action menu.
- -c: checkout selected commit - `-e, --edit`: edit selected commit through interactive rebase and skip action menu.
- `-c, --checkout`: checkout selected commit and skip action menu.
- `-y, --yes`: acknowledge all actions that will be taken and skip confirmation.
![flog demo](https://user-images.githubusercontent.com/43941510/82389843-810fa900-9a80-11ea-9653-544816eb9eb8.png) ![flog demo](https://user-images.githubusercontent.com/43941510/82389843-810fa900-9a80-11ea-9653-544816eb9eb8.png)
@ -477,39 +488,44 @@ edit, reset, revert and checkout the selected commits.
View and manage stash interactively. View and manage stash interactively.
- Default: list all stash and apply the selected stash. (Default: `apply`) - Default: list all stashes and apply the selected stash. (Default: `apply`).
- -f: list modified files and only stash selected files. Support multi selection. - `-h, --help`: show the help message of `dotbare fstash` and exit.
- -d: list all stash and delete selected stash. Support multi selection. - `-s, --select`: list modified files and stash the selected files. Support multi selection.
- -p: use `pop` instead of `apply`. (`pop` would remove the stash while `apply` preserve the stash) - `-d, --delete`: list all stashes and delete selected stash. Support multi selection.
- `-p, --pop`: use `pop` instead of `apply`. (`pop` would remove the stash while `apply` preserve the stash).
![fstash demo](https://user-images.githubusercontent.com/43941510/82390106-275bae80-9a81-11ea-8c7c-6573bb1ecada.png) ![fstash demo](https://user-images.githubusercontent.com/43941510/82390106-275bae80-9a81-11ea-8c7c-6573bb1ecada.png)
### fbackup ### fbackup
Backup all of the tracked dotfiles to \$DOTBARE_BACKUP directory. This is used also by Backup files to \$DOTBARE_BACKUP directory. This is particular useful when untracking files
`dotbare finit -u [URL]` for backing up conflicted checkout files. or migrating to new machines. This is used by `dotbare finit -u [URL]` for backing up conflicted checkout files.
- Default: backup all tracked dotfiles to \$DOTBARE_BACKUP directory. (Default: use `cp`) - Default: backup all tracked files to \$DOTBARE_BACKUP directory. (Default: use `cp` command).
- -s: list all tracked files and only backup selected files. Support multi selection. - `-h, --help`: show the help message of `dotbare fbackup` and exit.
- -p PATH: specify path to files and then backup. (This is mainly used by `dotbare finit -u [URL]`) - `-s, --select`: list all tracked files and only backup the selected files. Support multi selection.
- -m: use `mv` instead of `cp` to backup. (This is mainly used by `dotbare finit -u [URL]`) - `-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 ### fstat
Interactively toggle stage/unstage of files. This is less used compare to `dotbare fadd`, Display interactive git status menu. Toggle file stage/unstage status interactively.
it might get deprecated.
- `-h, --help`: show the help message of `dotbare fstat` and exit.
### finit ### finit
Initialise dotbare with a bare repository or add -u [URL] flag for migrating current Initialise dotbare with a bare repository or add -u [URL] flag for migrating existing dotfiles from
dotfiles to a new system. remote git repo to current system.
Note: do not use this command if you are using symlink/GNU stow. Note: do not use this command if you are using symlink/GNU stow and want to keep your current setup.
- Default: initialise a git bare repository at \$DOTBARE_DIR - Default: init the bare repository at \$DOTBARE_DIR.
- -u URL: migrate existing bare repository from remote to current system. - `-h, --help`: show the help message of `dotbare finit` and exit.
- -s: if you have defined submodules in your bare repo (i.e. containes .gitmodule), add -s - `-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. flag to clone submodules as well during migration.
- `-y, --yes`: acknowledge all actions that will be taken and skip confirmation.
### funtrack ### funtrack
@ -518,39 +534,54 @@ for files and then later on resume tracking changes.
**Note: This command has severe limitations.** **Note: This command has severe limitations.**
By default, selected files are permanently untracked starting from next commit. By default, selected files are permanently untracked from git. Selected files will be
It will not remove it from history. And if your other system pull down the new commit, remove from index while keeping the file in your current system. However, when your other
the untracked files on the other system will actually get removed by git. This is a limitation 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 the files. 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. 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). 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 `dotbare funtrack` does come with capabilities to temporarily untrack files, which will not
actually remove the untracked files from other system. However, this is **NOT** recommended 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). 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. - Default: list all tracked files and permanently untrack the selected files. Support multi selection.
- -s: list all tracked files and temporarily untrack changes of the selected files. Support multi selection. - `-h, --help`: show the help message of `dotbare funtrack` and exit.
- -S: list all tracked files and resume tracking changes of the selected files. - `-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 ### fupgrade
Update dotbare to the latest version in master. It basically just pull down changes from master, Update dotbare to the latest master. It will perform a `git pull --rebase --stat` and also
except you don't have to cd into dotbare directory, you can run this command any where. 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 ## Tips and Tricks
- Most commands related to files support multi selection (default fzf setting is TAB) - 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 - Most commands related to commits and branches doesn't support multi selection.
- Checkout fzf [doc](https://github.com/junegunn/fzf/blob/97a725fbd0e54cbc07e4d72661ea2bd2bb7c01c1/man/man1/fzf.1#L648) - Checkout fzf [doc](https://github.com/junegunn/fzf/blob/97a725fbd0e54cbc07e4d72661ea2bd2bb7c01c1/man/man1/fzf.1#L648)
for more default fzf keybinds information. for more default fzf keybinds information.
- Alias dotbare to shorter words to type less - Alias dotbare to shorter words to type less.
```sh ```sh
alias db=dotbare alias dots=dotbare
``` ```
- Create keybinds for dotbare (e.g. bind ctrl-g to launch fedit and edit files) - Create keybinds for dotbare (e.g. bind ctrl-g to launch fedit and edit files).
```sh ```sh
# zsh example # zsh example
@ -580,31 +611,43 @@ except you don't have to cd into dotbare directory, you can run this command any
echo ".cfg" >> $HOME/.gitignore echo ".cfg" >> $HOME/.gitignore
``` ```
- Define a custom vim command to select dotfiles using [fzf.vim](https://github.com/junegunn/fzf.vim)
```vim
command! Dots call fzf#run(fzf#wrap({
\ 'source': 'dotbare ls-files --full-name --directory "${DOTBARE_TREE}" | awk -v home="$HOME/" "{print home \$0}"',
\ 'sink': 'e',
\ 'options': [ '--multi', '--preview', 'cat {}' ]
\ }))
```
## Testing ## Testing
dotbare is unit tested on a _best effort_ due the nature of fzf which require human input. `dotbare` is unit tested using [bats](https://github.com/bats-core/bats-core). A very weird mock tests are implemented using PATH override method.
Mock test are coming if I could make it work. This will be improved later and documented in a dedicated README in tests folder for more readability and extensibility.
Some functions may have a lot more coverage than others, so please fire up issues if something went wrong. Not all functions have 100% coverage and lots of user interaction cannot be effectively tested, please fire up issues if something went wrong.
dotbare uses [bats](https://github.com/bats-core/bats-core) to test individual functions.
I've added AWSCodeBuild to CI/CD just for my personal practice, if you are interested in what's happening in AWSCodeBuild I've added AWSCodeBuild to CI/CD to build the docker image. It is mainly for my personal practice. If you are interested in what's happening in AWSCodeBuild
you could checkout my cloudformation [template](https://github.com/kazhala/AWSCloudFormationStacks/blob/master/CICD_dotbare.yaml). you could checkout my cloudformation [template](https://github.com/kazhala/AWSCloudFormationStacks/blob/master/CICD_dotbare.yaml).
## Contributing ## Contributing
Please help me out by pointing out things that I could improve, I've only been > A CONTRIBUTING.md is coming.
scripting for a few months and are still adapting many new things every day. PR are always welcome
Please help me out by pointing out things that I could improve.
I've only been scripting for a few months and are still learning many new things every day. PR are always welcome
and please fire up issues if something went wrong. and please fire up issues if something went wrong.
Leave a star if possible :) Leave a star :)
## Coming up ## Coming up
- [ ] Improve unit test with mocking - [x] Improve unit test with mocking
- [x] Support submodules during migration - [x] Support submodules during migration
- [ ] Command line completion for dotbare in zsh - [ ] Command line completion for dotbare in zsh
- [x] Command line completion for dotbare in bash - [x] Command line completion for dotbare in bash
- [ ] Command line completion for git commands
- [ ] Man page - [ ] Man page
- [x] Installation method - [x] Installation method
@ -618,6 +661,7 @@ for it. I hope you find it useful and enjoy it, thanks!
- credit to [forgit](https://github.com/wfxr/forgit) for inspiration. - credit to [forgit](https://github.com/wfxr/forgit) for inspiration.
- credit to [fzf](https://github.com/junegunn/fzf) for fzf. - credit to [fzf](https://github.com/junegunn/fzf) for fzf.
- credit to [OMZ](https://github.com/ohmyzsh/ohmyzsh) for upgrading method.
- credit to [this](https://www.atlassian.com/git/tutorials/dotfiles) post for step by step guide of setting up git bare repo. - credit to [this](https://www.atlassian.com/git/tutorials/dotfiles) post for step by step guide of setting up git bare repo.
- credit to [this](https://www.youtube.com/watch?v=tBoLDpTWVOM&t=288s) video for introducing git bare repo. - credit to [this](https://www.youtube.com/watch?v=tBoLDpTWVOM&t=288s) video for introducing git bare repo.

2
helper/set_variable.sh
View File

@ -15,7 +15,7 @@
export DOTBARE_DIR="${DOTBARE_DIR:-$HOME/.cfg/}" export DOTBARE_DIR="${DOTBARE_DIR:-$HOME/.cfg/}"
export DOTBARE_TREE="${DOTBARE_TREE:-$HOME}" export DOTBARE_TREE="${DOTBARE_TREE:-$HOME}"
export DOTBARE_BACKUP="${DOTBARE_BACKUP:-${XDG_DATA_HOME:-$HOME/.local/share}/dotbare}" export DOTBARE_BACKUP="${DOTBARE_BACKUP:-${XDG_DATA_HOME:-$HOME/.local/share}/dotbare}"
export DOTBARE_VERSION="v1.1.0" export DOTBARE_VERSION="v1.2.0"
export EDITOR="${EDITOR:-vim}" export EDITOR="${EDITOR:-vim}"
if [[ -z "${DOTBARE_KEY}" ]]; then if [[ -z "${DOTBARE_KEY}" ]]; then

10
scripts/fadd
View File

@ -22,13 +22,13 @@ source "${mydir}"/../helper/git_query.sh
function usage() { function usage() {
echo -e "Usage: dotbare fadd [-h] [-f] [-d] ...\n" echo -e "Usage: dotbare fadd [-h] [-f] [-d] ...\n"
echo -e "Select files/directory or modified files through fzf" echo -e "Select files/directories or modified files through fzf."
echo -e "Stage the selected file to the dotfile gitbare repo\n" echo -e "Stage the selected file to the dotfile gitbare repo.\n"
echo -e "Default: list all modified files and stage the selected files.\n" echo -e "Default: list all modified files and stage the selected files.\n"
echo -e "optional arguments:" echo -e "optional arguments:"
echo -e " -h, --help\t\tshow this help message and exit" echo -e " -h, --help\t\tshow this help message and exit."
echo -e " -f, --file\t\tselect a file in current directory and stage it" echo -e " -f, --file\t\tselect files in current directory and stage the selected files."
echo -e " -d, --dir\t\tselect a entire folder to stage" echo -e " -d, --dir\t\tselect folders in current directory and stage the selected folders."
} }
####################################### #######################################

14
scripts/fbackup
View File

@ -23,14 +23,14 @@ source "${mydir}"/../helper/git_query.sh
function usage() { function usage() {
echo -e "Usage: dotbare fbackup [-h] [-m] [-s] [-p PATH] ...\n" echo -e "Usage: dotbare fbackup [-h] [-m] [-s] [-p PATH] ...\n"
echo -e "Backup files to ${DOTBARE_BACKUP}" echo -e "Backup files to ${DOTBARE_BACKUP}."
echo -e "This is useful when untracking files or migrating on new machines\n" echo -e "This is useful when untracking files or migrating to new machines.\n"
echo -e "Default: backup every tracked files using cp to ${DOTBARE_BACKUP} directory\n" echo -e "Default: backup all tracked files using cp command to ${DOTBARE_BACKUP} directory.\n"
echo -e "optional arguments:" echo -e "optional arguments:"
echo -e " -h, --help\t\tshow this help message and exit" echo -e " -h, --help\t\tshow this help message and exit."
echo -e " -s, --select\t\tselect individual file through fzf and backup" echo -e " -s, --select\t\tlist all tracked files and only backup the selected files."
echo -e " -p PATH, --path PATH\tsepcify path of files to backup" echo -e " -p PATH, --path PATH\tsepcify path of files to backup."
echo -e " -m, --move\t\tuse mv command for backup instead of default cp" echo -e " -m, --move\t\tuse 'mv' instead of the default 'cp' command to backup."
} }
####################################### #######################################

20
scripts/fcheckout
View File

@ -26,17 +26,17 @@ source "${mydir}"/../helper/git_query.sh
function usage() { function usage() {
echo -e "Usage: dotbare fcheckout [-h] [-s] [-b] [-c] [-y] ...\n" echo -e "Usage: dotbare fcheckout [-h] [-s] [-b] [-c] [-y] ...\n"
echo -e "Checkout files/commit/branch using fzf" echo -e "Select files/commit/branch through fzf and checkout the selected objects."
echo -e "files: checkout the version in HEAD or in a specific commit (reset files content back to the selected commit)" echo -e "Files: checkout the version in HEAD or in a specific commit (reset files content back to the selected commit)."
echo -e "branch: switch to the selected branch" echo -e "Branch: switch to the selected branch."
echo -e "commit: switch to a specific commit\n" echo -e "Commit: switch to a specific commit.\n"
echo -e "Default: checkout files back to HEAD (Reset changes back to HEAD)\n" echo -e "Default: list all modified files and reset selected files back to HEAD.\n"
echo -e "optional arguments:" echo -e "optional arguments:"
echo -e " -h, --help\t\tshow this help message and exit" echo -e " -h, --help\t\tshow this help message and exit."
echo -e " -s, --select\t\tsearch all files and select a commit to checkout for selected files" echo -e " -s, --select\t\tlist all tracked files and select a commit to checkout the selected files."
echo -e " -b, --branch\t\tlist all branch and checkout/switch the selected branch" echo -e " -b, --branch\t\tlist all branch and checkout/switch the selected branch."
echo -e " -c, --commit\t\tlist all commits and checkout selected commit" echo -e " -c, --commit\t\tlist all commits and checkout selected commit."
echo -e " -y, --yes\t\tconfirm action by default and skip confirmation" echo -e " -y, --yes\t\tacknowledge all actions that will be taken and skip confirmation."
} }
action_type="modified" action_type="modified"

10
scripts/fedit
View File

@ -22,12 +22,12 @@ source "${mydir}"/../helper/git_query.sh
function usage() { function usage() {
echo -e "Usage: dotbare fedit [-h] [-m] [-c] ...\n" echo -e "Usage: dotbare fedit [-h] [-m] [-c] ...\n"
echo -e "Select files/commits through fzf and edit selected files/commits in EDITOR\n" echo -e "Select files/commits through fzf and edit selected files/commits in EDITOR.\n"
echo -e "Default: list all tracked dotfiles and edit the selected files\n" echo -e "Default: list all tracked dotfiles and edit the selected files.\n"
echo -e "optional arguments:" echo -e "optional arguments:"
echo -e " -h, --help\t\tshow this help message and exit" echo -e " -h, --help\t\tshow this help message and exit."
echo -e " -m, --modified\t\tonly display and edit modified files" echo -e " -m, --modified\tonly list and edit selected modified files."
echo -e " -c, --commit\t\tedit commit using interactive rebase" echo -e " -c, --commit\t\tlist commit and edit the selected commit through interactive rebase."
} }
edit_type="all" edit_type="all"

18
scripts/finit
View File

@ -23,17 +23,19 @@ source "${mydir}"/../helper/get_confirmation.sh
function usage() { function usage() {
echo -e "Usage: dotbare finit [-h] [-y] [-s] [-u URL] ...\n" echo -e "Usage: dotbare finit [-h] [-y] [-s] [-u URL] ...\n"
echo -e "Init the git bare repository if doesn't exist" echo -e "Init the git bare repository if doesn't exist or migrate existing dotfiles to current system."
# shellcheck disable=SC2016 # shellcheck disable=SC2016
echo -e 'The bare repository will be initialised under $DOTBARE_DIR, default to $HOME/.cfg if not set' echo -e 'The bare repository will be initialised under $DOTBARE_DIR, default to $HOME/.cfg if not set.'
# shellcheck disable=SC2016 # shellcheck disable=SC2016
echo -e 'It will track $DOTBARE_TREE, default to $HOME if not set\n' echo -e 'It will track $DOTBARE_TREE, default to $HOME if not set.\n'
echo -e "Default: init the bare repository at $DOTBARE_DIR\n" echo -e "Migration example:"
echo -e "dotbare finit -u URL --submodule\n"
echo -e "Default: init the bare repository at $DOTBARE_DIR.\n"
echo -e "optional arguments:" echo -e "optional arguments:"
echo -e " -h, --help\t\tshow this help message and exit" echo -e " -h, --help\t\tshow this help message and exit."
echo -e " -u URL, --url URL\tmigrate existing dotfiles from the git URL to current system" echo -e " -u URL, --url URL\tmigrate existing dotfiles from remote git repo to current system."
echo -e " -s, --submodule\tclone submodules after checkout" echo -e " -s, --submodule\tclone submodules during migration."
echo -e " -y, --yes\t\tconfirm action by default and skip confirmation" echo -e " -y, --yes\t\tacknowledge all actions that will be taken and skip confirmation."
} }
remote_url="" remote_url=""

18
scripts/flog
View File

@ -26,16 +26,16 @@ source "${mydir}"/../helper/get_confirmation.sh
function usage() { function usage() {
echo -e "Usage: dotbare flog [-h] [-r] [-R] [-e] [-c] [-y] ...\n" echo -e "Usage: dotbare flog [-h] [-r] [-R] [-e] [-c] [-y] ...\n"
echo -e "Interactive log viewer with action menu" echo -e "Interactive log viewer with action menu."
echo -e "Action menu contains command including revert|reset|edit|checkout|exit\n" echo -e "Action menu contains options including revert|reset|edit|checkout|exit.\n"
echo -e "Default: list all commits and prompt a menu for user to take action on the selected commit\n" echo -e "Default: list all commits and prompt a menu to select action to perform.\n"
echo -e "optional arguments:" echo -e "optional arguments:"
echo -e " -h, --help\t\tshow this help message and exit" echo -e " -h, --help\t\tshow this help message and exit."
echo -e " -r, --revert\t\trevert the selected commit" echo -e " -r, --revert\t\trevert the selected commit and skip action menu."
echo -e " -R, --reset\t\treset HEAD back to selected commit" echo -e " -R, --reset\t\treset HEAD back to selected commit and skip action menu."
echo -e " -e, --edit\t\tedit selected commit through interactive rebase" echo -e " -e, --edit\t\tedit selected commit through interactive rebase and skip action menu."
echo -e " -c, --checkout\t\tcheckout selected commit" echo -e " -c, --checkout\tcheckout selected commit and skip action menu."
echo -e " -y, --yes\t\tconfirm action by default and skip confirmation" echo -e " -y, --yes\t\tacknowledge all actions that will be taken and skip confirmation."
} }
####################################### #######################################

16
scripts/freset
View File

@ -28,15 +28,15 @@ source "${mydir}"/../helper/git_query.sh
function usage() { function usage() {
echo -e "Usage: dotbare freset [-h] [-c] [-S] [-H] [-y] ...\n" echo -e "Usage: dotbare freset [-h] [-c] [-S] [-H] [-y] ...\n"
echo -e "Reset/Unstage the selected staged file" echo -e "Reset(unstage) the selected staged files."
echo -e "Or reset the HEAD to certain commits by using -c flag\n" echo -e "Reset the HEAD to certain commits by using -c flag.\n"
echo -e "Default: unstage the selected files\n" echo -e "Default: unstage the selected files.\n"
echo -e "optional arguments:" echo -e "optional arguments:"
echo -e " -h, --help\t\tshow this help message and exit" echo -e " -h, --help\t\tshow this help message and exit."
echo -e " -c, --commit\t\treset commit to certain commit, default --mixed flag, reset HEAD to certain commit put all changes into modified state" echo -e " -c, --commit\t\treset commit to certain commit, default --mixed flag, reset HEAD to certain commit put all changes into modified state."
echo -e " -S, --soft\t\treset commit using --soft flag, reset HEAD to certain commit without modify working tree" echo -e " -S, --soft\t\treset commit using --soft flag, reset HEAD to certain commit without modify working tree."
echo -e " -H, --hard\t\treset commit using --hard flag, reset HEAD to certain commit discard all changes from the working tree" echo -e " -H, --hard\t\treset commit using --hard flag, reset HEAD to certain commit discard all changes from the working tree."
echo -e " -y, --yes\t\tconfirm action by default and skip confirmation" echo -e " -y, --yes\t\tacknowledge all actions that will be taken and skip confirmation."
} }
reset_option="--mixed" reset_option="--mixed"

12
scripts/fstash
View File

@ -25,13 +25,13 @@ source "${mydir}"/../helper/git_query.sh
function usage() { function usage() {
echo -e "Usage: dotbare fstash [-h] [-s] [-d] [-p] ...\n" echo -e "Usage: dotbare fstash [-h] [-s] [-d] [-p] ...\n"
echo -e "save/apply/delect stash using fzf, also supports stashing individual file\n" echo -e "View and manage stash interactively.\n"
echo -e "Default: running fstash will apply the selected stash\n" echo -e "Default: list all stashes and apply the selected stash.\n"
echo -e "optional arguments:" echo -e "optional arguments:"
echo -e " -h, --help\t\tshow this help message and exit" echo -e " -h, --help\t\tshow this help message and exit."
echo -e " -s, --select\t\tselect modified files through fzf and stash them" echo -e " -s, --select\t\tlist modified files and stash the selected files."
echo -e " -d, --delete\t\tdelete the selected stash from stash list" echo -e " -d, --delete\t\tlist all stashes and delete the selected stash from stash list."
echo -e " -p, --pop\t\tuse pop instead of apply when retrieving stash" echo -e " -p, --pop\t\tuse 'stash pop' instead of 'stash apply'."
} }
stash_command="apply" stash_command="apply"

6
scripts/fstat
View File

@ -21,10 +21,10 @@ source "${mydir}"/../helper/git_query.sh
function usage() { function usage() {
echo -e "Usage: dotbare fstat [-h] ...\n" echo -e "Usage: dotbare fstat [-h] ...\n"
echo -e "Display interactive git status menu" echo -e "Display interactive git status menu."
echo -e "Toggle file stage/unstage interactively\n" echo -e "Toggle file stage/unstage interactively.\n"
echo -e "optional arguments:" echo -e "optional arguments:"
echo -e " -h, --help\t\tshow this help message and exit" echo -e " -h, --help\t\tshow this help message and exit."
} }
while [[ "$#" -gt 0 ]]; do while [[ "$#" -gt 0 ]]; do

12
scripts/funtrack
View File

@ -24,8 +24,8 @@ source "${mydir}"/../helper/get_confirmation.sh
function usage() { function usage() {
echo -e "Usage: dotbare funtrack [-h] [-t] [-r] [-y] ...\n" echo -e "Usage: dotbare funtrack [-h] [-t] [-r] [-y] ...\n"
echo -e "Untrack selected files from git\n" echo -e "Untrack selected files from git.\n"
echo -e "Default: launch fzf and the selected files will be untracked (using git rm --cached filename).\n" echo -e "Default: list all tracked files and permanently untrack the selected files (using git rm --cached filename).\n"
echo -e "Files will be remove from index while keeping the file in your current system." echo -e "Files will be remove from index while keeping the file in your current system."
echo -e "However, when your other computers pull down the changes, the untracked files will be deleted." echo -e "However, when your other computers pull down the changes, the untracked files will be deleted."
echo -e "Make sure to run dotbare fbackup before pulling down the changes.\n" echo -e "Make sure to run dotbare fbackup before pulling down the changes.\n"
@ -33,10 +33,10 @@ function usage() {
echo -e "untrack a file but keeping the files when other computers pull down the changes." echo -e "untrack a file but keeping the files when other computers pull down the changes."
echo -e "More information please refere to dotbare's github.\n" echo -e "More information please refere to dotbare's github.\n"
echo -e "optional arguments:" echo -e "optional arguments:"
echo -e " -h, --help\t\tshow this help message and exit" echo -e " -h, --help\t\tshow this help message and exit."
echo -e " -t, --temp\t\ttemporarily ignore changes of the selected files" echo -e " -t, --temp\t\tlist all tracked files and temporarily ignore changes of the selected files."
echo -e " -r, --resume\t\tresume tracking changes of the selected files" echo -e " -r, --resume\t\tlist all tracked files and resume tracking changes of the selected files."
echo -e " -y, --yes\t\tconfirm action by default and skip confirmation" echo -e " -y, --yes\t\tacknowledge all actions that will be taken and skip confirmation."
} }
track_type="untrack" track_type="untrack"