diff --git a/README.markdown b/README.markdown index d2642ba..28e9643 100644 --- a/README.markdown +++ b/README.markdown @@ -2,77 +2,82 @@ ## Please post an issue if you would like to help out. -# SCM Breeze [![TravisCI](https://secure.travis-ci.org/ndbroadbent/scm_breeze.png?branch=master)](http://travis-ci.org/ndbroadbent/scm_breeze) +--- + +# SCM Breeze [![TravisCI](https://secure.travis-ci.org/scmbreeze/scm_breeze.png?branch=master)](http://travis-ci.org/scmbreeze/scm_breeze) > Streamline your SCM workflow. -**SCM Breeze** is a set of shell scripts (for `bash` and `zsh`) that enhance your interaction with git. It integrates with your shell to give you numbered file shortcuts, -a repository index with tab completion, and many other useful features. +**SCM Breeze** is a set of shell scripts (for `bash` and `zsh`) that enhance +your interaction with git. It integrates with your shell to give you numbered +file shortcuts, a repository index with tab completion, and many other useful +features. -
+![SCM Breeze Example Gif](http://i.imgur.com/3fD8cpo.gif) -- [SCM Breeze](#scm-breeze-) - - [Demos](#demos) + +- [Installation](#installation) +- [Usage](#usage) - [File Shortcuts](#file-shortcuts) - - [Git Status Shortcuts:](#git-status-shortcuts) - - ['ls' shortcuts:](#ls-shortcuts) - - [Other shortcuts](#other-shortcuts) - [Keyboard bindings](#keyboard-bindings) - [Repository Index](#repository-index) - [Linking External Project Design Directories](#linking-external-project-design-directories) - - [1) Create and configure a root design directory](#1-create-and-configure-a-root-design-directory) - - [2) Initialize design directories for your projects](#2-initialize-design-directories-for-your-projects) - - [3) Link existing design directories into your projects](#3-link-existing-design-directories-into-your-projects) - - [Contributing tools / scripts](#contributing-tools--scripts) -- [Installation](#installation) -- [Updating](#updating) -- [Uninstall](#uninstall) - [Configuration](#configuration) - - [1) Configure and use the provided SCM Breeze aliases](#1-configure-and-use-the-provided-scm-breeze-aliases) - - [2) Use your own aliases](#2-use-your-own-aliases) +- [Updating](#updating) +- [Uninstalling](#uninstalling) - [Notes about Tab Completion for Aliases](#notes-about-tab-completion-for-aliases) - - [Bash](#bash) - - [Zsh](#zsh) - [Contributing](#contributing) -
-## Demos +## Installation -Adding a range of files, and pressing `Ctrl+X, C` to commit: +```bash +git clone git://github.com/scmbreeze/scm_breeze.git ~/.scm_breeze +~/.scm_breeze/install.sh +source ~/.bashrc # or source ~/.zshrc +``` -
+The install script creates required default configs and adds the following line +to your `.bashrc` or `.zshrc`: -
+`[ -s "$HOME/.scm_breeze/scm_breeze.sh" ] && source "$HOME/.scm_breeze/scm_breeze.sh"` -
- -
- -## File Shortcuts - -SCM Breeze makes it really easy to work with changed files, and groups of changed files. -Whenever you view your SCM status, each modified path is stored in a numbered environment variable. -You can configure the variable prefix, which is 'e' by default. +**Note:** SCM Breeze performs much faster if you have ruby installed. -### Git Status Shortcuts: +## Usage + +
+ +### File Shortcuts + +SCM Breeze makes it really easy to work with changed files, and groups of +changed files. Whenever you view your SCM status, each modified path is stored +in a numbered environment variable. You can configure the variable prefix, +which is 'e' by default. + + +#### Git Status Shortcuts:
Git Status With Shortcuts

-### 'ls' shortcuts: + +#### 'ls' shortcuts:
Ls With Shortcuts

-These numbers (or ranges of numbers) can be used with any SCM or system command. +These numbers (or ranges of numbers) can be used with any SCM or system +command. -For example, if `ga` was your alias for `git add`, instead of typing something like: +For example, if `ga` was your alias for `git add`, instead of typing something +like: ```bash $ ga assets/git_breeze/config* assets/git_breeze/install.sh @@ -84,8 +89,8 @@ You can type this instead: $ ga $e2 $e3 $e11 ``` -But SCM Breeze aliases `ga` to the `git_add_shortcuts` function, -which is smart enough to expand integers and ranges, so all you need to type is: +But SCM Breeze aliases `ga` to the `git_add_shortcuts` function, which is smart +enough to expand integers and ranges, so all you need to type is: ```bash $ ga 2 3 11 @@ -97,8 +102,8 @@ And if you want to add all unstaged changes (files 1 to 10): $ ga 1-10 ``` -(Note that `ga` will also remove deleted files, unlike the standard `git add` command. -This behaviour can be turned off if you don't like it.) +(Note that `ga` will also remove deleted files, unlike the standard `git add` +command. This behaviour can be turned off if you don't like it.) You can also diff, reset or checkout a file by typing: @@ -110,8 +115,8 @@ $ gco 5 ``` -You can use these shortcuts with system commands by passing your command through `exec_scmb_expand_args` -(default alias is 'ge'): +You can use these shortcuts with system commands by passing your command +through `exec_scmb_expand_args` (default alias is 'ge'): ```bash @@ -125,19 +130,21 @@ $ ge echo 1-3 ``` -### Other shortcuts +#### Other shortcuts -SCM Breeze adds a number of aliases to your shell. Use `list_aliases` to view all the aliases and their corresponding commands. -You can filter aliases by adding a search string: `list_aliases git log` +SCM Breeze adds a number of aliases to your shell. Use `list_aliases` to view +all the aliases and their corresponding commands. You can filter aliases by +adding a search string: `list_aliases git log` -There's also a `git_aliases` command, which just shows aliases for `git` commands. You can also pass in additional filters, e.g. `git_aliases log`. +There's also a `git_aliases` command, which just shows aliases for `git` +commands. You can also pass in additional filters, e.g. `git_aliases log`. -## Keyboard bindings +### Keyboard bindings -Some of my most common git commands are `git add` and `git commit`, so I wanted these -to be as streamlined as possible. One way of speeding up commonly used commands is by binding them to -keyboard shortcuts. +Some of my most common git commands are `git add` and `git commit`, so I wanted +these to be as streamlined as possible. One way of speeding up commonly used +commands is by binding them to keyboard shortcuts. Here are the default key bindings: @@ -145,14 +152,13 @@ Here are the default key bindings: * `CTRL`+`x` `SPACE` => `git_commit_all` - commit everything -The commit shortcuts use the `git_commit_prompt` function, which gives a simple prompt like this: +The commit shortcuts use the `git_commit_prompt` function, which gives a simple +prompt like this: -
-Git Commit All -
-
-(When using bash, this commit prompt gives you access to your bash history via the arrow keys.) -
+

(When using bash, this commit prompt gives +you access to your bash history via the arrow keys.)
And if you really want to speed up your workflow, you can type this: @@ -168,23 +174,26 @@ This sends the `HOME` key, followed by `git_add_and_commit`:
-## Repository Index +### Repository Index -The second feature is a repository index for all of your projects and submodules. -This gives you super-fast switching between your project directories, with tab completion, -and it can even tab-complete down to project subdirectories. -This means that you can keep your projects organized in subfolders, -but switch between them as easily as if they were all in one folder. +The second feature is a repository index for all of your projects and +submodules. This gives you super-fast switching between your project +directories, with tab completion, and it can even tab-complete down to project +subdirectories. This means that you can keep your projects organized in +subfolders, but switch between them as easily as if they were all in one +folder. -It's similar to [autojump](https://github.com/joelthelion/autojump), but it doesn't need to 'learn' anything, -and it can do SCM-specific stuff like: +It's similar to [autojump](https://github.com/joelthelion/autojump), but it +doesn't need to 'learn' anything, and it can do SCM-specific stuff like: -* Running a command for all of your repos (useful if you ever need to update a lot of remote URLs) +* Running a command for all of your repos (useful if you ever need to update a + lot of remote URLs) * Update all of your repositories via a cron task The default alias for `git_index` is 'c', which might stand for 'code' -You will first need to configure your repository directory, and then build the index: +You will first need to configure your repository directory, and then build the +index: ```bash $ c --rebuild @@ -192,10 +201,12 @@ $ c --rebuild # => ===== Indexed 64 repos in /home/ndbroadbent/code/.git_index ``` -Then you'll be able to switch between your projects, or show the list of indexed repos. +Then you'll be able to switch between your projects, or show the list of +indexed repos. -To switch to a project directory, you don't need to type the full project name. For example, -to switch to the `capistrano` project, you could type any of the following: +To switch to a project directory, you don't need to type the full project name. +For example, to switch to the `capistrano` project, you could type any of the +following: ```bash $ c capistrano @@ -214,19 +225,20 @@ $ c capistrano/lib/ # => cd ~/code/gems/capistrano/lib ``` -Or if you want to go to a subdirectory within the `~/code` directory, prefix the first argument with a `/`: +Or if you want to go to a subdirectory within the `~/code` directory, prefix +the first argument with a `/`: ```bash ~ $ c /gems ~/code/gems $ ``` -## Linking External Project Design Directories +### Linking External Project Design Directories -When you're creating logos or icons for a project that uses `git`, -have you ever wondered where you should store those `.psd` or `.xcf` files? -Do you commit all of your raw design files, or does it put you off that any changes to those files -will bloat your repository? +When you're creating logos or icons for a project that uses `git`, have you +ever wondered where you should store those `.psd` or `.xcf` files? Do you +commit all of your raw design files, or does it put you off that any changes to +those files will bloat your repository? Here were my goals when I set out to find a solution: @@ -235,166 +247,164 @@ Here were my goals when I set out to find a solution: * The design directory needed to be synchronized across all of my machines The simplest way for me to synchronize files was via my Dropbox account. -However, if you work with a larger team, you could set up a shared design directory on one -of your servers and synchronize it with `rsync`. +However, if you work with a larger team, you could set up a shared design +directory on one of your servers and synchronize it with `rsync`. -### 1) Create and configure a root design directory +#### 1) Create and configure a root design directory I created my root design directory at `~/Dropbox/Design`. -After you've created your root design directory, edit `~/.scmbrc` and set `root_design_dir` -to the directory you just created. -You can also configure the design directory that's created in each of your projects -(default: `design_assets`), as well as the subdirectories you would like to use. -The default base subdirectories are: Images, Backgrounds, Logos, Icons, Mockups, and Screenshots. +After you've created your root design directory, edit `~/.scmbrc` and set +`root_design_dir` to the directory you just created. You can also configure +the design directory that's created in each of your projects (default: +`design_assets`), as well as the subdirectories you would like to use. The +default base subdirectories are: Images, Backgrounds, Logos, Icons, Mockups, +and Screenshots. -After you have changed these settings, remember to run `source ~/.bashrc` or `source ~/.zshrc`. +After you have changed these settings, remember to run `source ~/.bashrc` or +`source ~/.zshrc`. -### 2) Initialize design directories for your projects +#### 2) Initialize design directories for your projects -To set up the design directories and symlinks, go to a project's directory and run: +To set up the design directories and symlinks, go to a project's directory and +run: ```bash design init ``` If your root directory is `~/Dropbox/Design`, directories will be created at -`~/Dropbox/Design/projects/my_project/Backgrounds`, `~/Dropbox/Design/projects/my_project/Icons`, etc. +`~/Dropbox/Design/projects/my_project/Backgrounds`, +`~/Dropbox/Design/projects/my_project/Icons`, etc. -It will then symlink the project from your root design directory into your project's design directory, -so you end up with: +It will then symlink the project from your root design directory into your +project's design directory, so you end up with: * `my_project/design_assets` -> `~/Dropbox/Design/projects/my_project` It also adds this directory to `.git/info/exclude` so that git ignores it. -If you use the git repository index, -you can run the following batch command to set up these directories for all of your git repos at once: +If you use the git repository index, you can run the following batch command to +set up these directories for all of your git repos at once: ```bash git_index --batch-cmd design init ``` - If you want to remove any empty design directories, run: ```bash design trim ``` -And if you want to remove all of a project's design directories, even if they contain files: +And if you want to remove all of a project's design directories, even if they +contain files: ```bash design rm ``` -### 3) Link existing design directories into your projects +#### 3) Link existing design directories into your projects -If you've set up your design directories on one machine, you'll want them -to be synchronized across all of your other development machines. +If you've set up your design directories on one machine, you'll want them to be +synchronized across all of your other development machines. -Just run the following command on your other machines after you've configured the root design directory: +Just run the following command on your other machines after you've configured +the root design directory: ```bash design link ``` -This uses your git index to figure out where to create the symlinks. -If you don't use the git index, the same outcome could be achieved by running 'design init' -for each of the projects. +This uses your git index to figure out where to create the symlinks. If you +don't use the git index, the same outcome could be achieved by running 'design +init' for each of the projects. +## Configuration -## Contributing tools / scripts +SCM Breeze is configured via automatically installed `~/.*.scmbrc` files. To +change git configuration, edit `~/.git.scmbrc`. -If you have any awesome SCM scripts lurking in your `.bashrc` or `.zshrc`, -please feel free to send me a pull request. -It would be cool to make this project into an [oh-my-zsh](https://github.com/robbyrussell/oh-my-zsh) for SCMs. +Each feature is modular, so you are free to ignore the parts you don't want to +use. Just comment out the relevant line in `~/.scm_breeze/scm_breeze.sh`. + +**Note:** After changing any settings, you will need to run `source ~/.bashrc` +(or `source ~/.zshrc`) + +I know we grow attached to the aliases we use every day, so I've made the alias +system completely customizable. You have two options when it comes to aliases: -# Installation +### 1) Configure and use the provided SCM Breeze aliases -```bash -git clone git://github.com/scmbreeze/scm_breeze.git ~/.scm_breeze -~/.scm_breeze/install.sh -source ~/.bashrc # or source ~/.zshrc -``` - -The install script creates required default configs and adds the following line to your `.bashrc` or `.zshrc`: - -`[ -s "$HOME/.scm_breeze/scm_breeze.sh" ] && source "$HOME/.scm_breeze/scm_breeze.sh"` - -**Note:** SCM Breeze performs much faster if you have ruby installed. +Just tweak the aliases in `~/.git.scmbrc`. You can also change or remove any +keyboard shortcuts. These aliases also come with tab completion. For example, +you can type `gco ` to tab complete your list of branches. -# Updating +### 2) Use your own aliases -Please run `update_scm_breeze` to fetch the latest code. This will update SCM Breeze from Github, -and will create or patch your `~/.*.scmbrc` config files if any new settings are added. +In your `git.scmbrc` config file, just set the `git_setup_aliases` option to +`no`. Your existing git aliases will then be used, and you will still be able +to use the numeric shortcuts feature. SCM Breeze creates a function to wrap +the 'git' command, which expands numeric arguments, and uses `hub` if +available. -# Uninstall +A few aliases will still be defined for the central SCM Breeze features, such +as `gs` for the extended `git status`, and `ga` for the `git add` function. + +If you already have an alias like `alias gco="git checkout"`, you can now type +`gco 1` to checkout the first file in the output of SCM Breeze's `git status`. + + +## Notes about Tab Completion for Aliases + +### Bash + +If you use your own aliases, SCM Breeze will **not** set up bash tab completion +for your aliases. You will need to set that up yourself. + + +### Zsh + +You just need to set the option: `setopt no_complete_aliases` (oh-my-zsh sets +this by default). Zsh will then expand aliases like `gb` to `git branch`, and +use the completion for that. + + +## Updating + +Please run `update_scm_breeze` to fetch the latest code. This will update SCM +Breeze from Github, and will create or patch your `~/.*.scmbrc` config files if +any new settings are added. + + +## Uninstalling ```bash ~/.scm_breeze/uninstall.sh ``` -The uninstall script removes the following line from your `.bashrc` or `.zshrc`: +The uninstall script removes the following line from your `.bashrc` or +`.zshrc`: `[ -s "$HOME/.scm_breeze/scm_breeze.sh" ] && source "$HOME/.scm_breeze/scm_breeze.sh"` -# Configuration -SCM Breeze is configured via automatically installed `~/.*.scmbrc` files. -To change git configuration, edit `~/.git.scmbrc`. +## Contributing -Each feature is modular, so you are free to ignore the parts you don't want to use. -Just comment out the relevant line in `~/.scm_breeze/scm_breeze.sh`. - -**Note:** After changing any settings, you will need to run `source ~/.bashrc` (or `source ~/.zshrc`) - -I know we grow attached to the aliases we use every day, so I've made the alias system completely customizable. -You have two options when it comes to aliases: - -### 1) Configure and use the provided SCM Breeze aliases - -Just tweak the aliases in `~/.git.scmbrc`. You can also change or remove any keyboard shortcuts. -These aliases also come with tab completion. For example, you can type `gco ` to tab complete your list of branches. - -### 2) Use your own aliases - -In your `git.scmbrc` config file, just set the `git_setup_aliases` option to `no`. -Your existing git aliases will then be used, and you will still be able to use the numeric shortcuts feature. -SCM Breeze creates a function to wrap the 'git' command, which expands numeric arguments, and uses `hub` if available. - -A few aliases will still be defined for the central SCM Breeze features, such as `gs` for the extended `git status`, -and `ga` for the `git add` function. - -If you already have an alias like `alias gco="git checkout"`, -you can now type `gco 1` to checkout the first file in the output of SCM Breeze's `git status`. - -# Notes about Tab Completion for Aliases - -### Bash - -If you use your own aliases, SCM Breeze will **not** set up bash tab completion for your aliases. -You will need to set that up yourself. - -### Zsh - -You just need to set the option: `setopt no_complete_aliases` (oh-my-zsh sets this by default). -Zsh will then expand aliases like `gb` to `git branch`, and use the completion for that. - -# Contributing - -SCM Breeze lives on Github at [https://github.com/ndbroadbent/scm_breeze](https://github.com/ndbroadbent/scm_breeze) - -Please feel free to fork and send pull requests, especially if you would like to build these features -for Mercurial, SVN, etc. +SCM Breeze lives on Github at +[`scmbreeze/scm_breeze`](https://github.com/scmbreeze/scm_breeze) +If you have any awesome SCM scripts lurking in your `.bashrc` or `.zshrc`, +please feel free to send me a pull request. It would be cool to make this +project into an [oh-my-zsh](https://github.com/robbyrussell/oh-my-zsh) for +SCMs. ***Enjoy!***