XorA
/
bash-it
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add linebreaks for long single-line paragraphs 

Also some small punctuation and phrasing improvements in README.md
pull/1052/head
Jean Jordaan 2017-10-02 12:23:25 +07:00
parent 3f839d5ac2
commit 16ad3e6149
2 changed files with 135 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
CONTRIBUTING.md
View File

@ -1,38 +1,56 @@
# Contribution Guidelines
When contributing a new feature, a bug fix, a new theme, or any other change to Bash-it, please consider the following guidelines. Most of this is common sense, but please try to stick to the conventions listed here.
When contributing a new feature, a bug fix, a new theme, or any other change to Bash-it, please consider the following guidelines.
Most of this is common sense, but please try to stick to the conventions listed here.
## Issues
* When opening a new issue in the issue tracker, please include information about which _Operating System_ you're using, and which version of _Bash_.
* In many cases, it also makes sense to show which Bash-it plugins you are using. This information can be obtained using `bash-it show plugins`.
* If the issue happens while loading Bash-it, please also include your `~/.bash_profile` or `~/.bashrc` file, as well as the install location of Bash-it (default should be `~/.bash_it`).
* When reporting a bug or requesting a new feature, consider providing a Pull Request that fixes the issue or can be used as a starting point for the new feature. Don't be afraid, most things aren't that complex...
* In many cases, it also makes sense to show which Bash-it plugins you are using.
This information can be obtained using `bash-it show plugins`.
* If the issue happens while loading Bash-it, please also include your `~/.bash_profile` or `~/.bashrc` file,
as well as the install location of Bash-it (default should be `~/.bash_it`).
* When reporting a bug or requesting a new feature, consider providing a Pull Request that fixes the issue or can be used as a starting point for the new feature.
Don't be afraid, most things aren't that complex...
## Pull Requests
* Fork the Bash-it repo, create a new feature branch from _master_ and apply your changes there. Create a _Pull Request_ from your feature branch against Bash-it's _master_ branch.
* Limit each Pull Request to one feature. Don't bundle multiple features/changes (e.g. a new _Theme_ and a fix to an existing plugin) into a single Pull Request - create one PR for the theme, and a separate PR for the fix.
* For complex changes, try to _squash_ your changes into a single commit. Don't create a PR consisting of 20 commits that show your work in progress. Before you create the PR, _squash_ your changes into a single commit.
* Fork the Bash-it repo, create a new feature branch from _master_ and apply your changes there.
Create a _Pull Request_ from your feature branch against Bash-it's _master_ branch.
* Limit each Pull Request to one feature.
Don't bundle multiple features/changes (e.g. a new _Theme_ and a fix to an existing plugin) into a single Pull Request - create one PR for the theme, and a separate PR for the fix.
* For complex changes, try to _squash_ your changes into a single commit.
Don't create a PR consisting of 20 commits that show your work in progress.
Before you create the PR, _squash_ your changes into a single commit.
## Code Style
* Try to stick to the existing code style. Please don't reformat or change the syntax of existing code simply because you don't like that style.
* Indentation is using spaces, not tabs. Most of the code is indented with 2 spaces, some with 4 spaces. Please try to stick to 2 spaces. If you're using an editor that supports [EditorConfig](http://EditorConfig.org), the editor should automatically use the settings defined in Bash-it's [.editorconfig file](.editorconfig).
* When creating new functions, please use a dash ("-") to separate the words of the function's name, e.g. `my-new-function`. Don't use underscores, e.g. `my_new_function`.
* Indentation is using spaces, not tabs. Most of the code is indented with 2 spaces, some with 4 spaces. Please try to stick to 2 spaces.
If you're using an editor that supports [EditorConfig](http://EditorConfig.org), the editor should automatically use the settings defined in Bash-it's [.editorconfig file](.editorconfig).
* When creating new functions, please use a dash ("-") to separate the words of the function's name, e.g. `my-new-function`.
Don't use underscores, e.g. `my_new_function`.
* Internal functions that aren't to be used by the end user should start with an underscore, e.g. `_my-new-internal-function`.
* Use the provided meta functions to document your code, e.g. `about-plugin`, `about`, `group`, `param`, `example`. This will make it easier for other people to use your new functionality. Take a look at the existing code for an example (e.g. [the base plugin](plugins/available/base.plugin.bash)).
* When adding files, please use the existing file naming conventions, e.g. plugin files need to end in `.plugin.bash`. This is important for the installation functionality.
* Use the provided meta functions to document your code, e.g. `about-plugin`, `about`, `group`, `param`, `example`.
This will make it easier for other people to use your new functionality.
Take a look at the existing code for an example (e.g. [the base plugin](plugins/available/base.plugin.bash)).
* When adding files, please use the existing file naming conventions, e.g. plugin files need to end in `.plugin.bash`.
This is important for the installation functionality.
* When using the `$BASH_IT` variable, please always enclose it in double quotes to ensure that the code also works when Bash-it is installed in a directory that contains spaces in its name: `for f in "${BASH_IT}/plugins/available"/*.bash ; do echo "$f" ; done`
* Bash-it supports Bash 3.2 and higher. Please don't use features only available in Bash 4, such as associative arrays.
## Unit Tests
When adding features or making changes/fixes, please run our growing unit test suite to ensure that you did not break existing functionality. The test suite does not cover all aspects of Bash-it, but please run it anyway to verify that you did not introduce any regression issues.
When adding features or making changes/fixes, please run our growing unit test suite to ensure that you did not break existing functionality.
The test suite does not cover all aspects of Bash-it, but please run it anyway to verify that you did not introduce any regression issues.
Any code pushed to GitHub as part of a Pull Request will automatically trigger a continuous integration build on [Travis CI](https://travis-ci.org/Bash-it/bash-it), where the test suite is run on both Linux and macOS. The Pull Request will then show the result of the Travis build, indicating whether all tests ran fine, or whether there were issues. Please pay attention to this, Pull Requests with build issues will not be merged.
Any code pushed to GitHub as part of a Pull Request will automatically trigger a continuous integration build on [Travis CI](https://travis-ci.org/Bash-it/bash-it), where the test suite is run on both Linux and macOS.
The Pull Request will then show the result of the Travis build, indicating whether all tests ran fine, or whether there were issues.
Please pay attention to this, Pull Requests with build issues will not be merged.
Adding new functionality or changing existing functionality is a good opportunity to increase Bash-it's test coverage. When you're changing the Bash-it codebase, please consider adding some unit tests that cover the new or changed functionality. Ideally, when fixing a bug, a matching unit test that verifies that the bug is no longer present, is added at the same time.
Adding new functionality or changing existing functionality is a good opportunity to increase Bash-it's test coverage.
When you're changing the Bash-it codebase, please consider adding some unit tests that cover the new or changed functionality.
Ideally, when fixing a bug, a matching unit test that verifies that the bug is no longer present, is added at the same time.
To run the test suite, simply execute the following in the directory where you cloned Bash-it:
@ -40,15 +58,21 @@ To run the test suite, simply execute the following in the directory where you c
test/run
```
This command will clone the [Bats Test Framework](https://github.com/sstephenson/bats) to a local directory and then run the test suite found in the [test](test) folder. The test script will execute each test in turn, and will print a status for each test case.
This command will clone the [Bats Test Framework](https://github.com/sstephenson/bats) to a local directory and then run the test suite found in the [test](test) folder.
The test script will execute each test in turn, and will print a status for each test case.
When adding new test cases, please take a look at the existing test cases for examples.
## Features
* When adding new completions or plugins, please don't simply copy existing tools into the Bash-it codebase, try to load/integrate the tools instead. An example is using `nvm`: Instead of copying the existing `nvm` script into Bash-it, the `nvm.plugin.bash` file tries to load an existing installation of `nvm`. This means an additional step for the user (installing `nvm` from its own repo, or through a package manager), but it will also ensure that `nvm` can be upgraded in an easy way.
* When adding new completions or plugins, please don't simply copy existing tools into the Bash-it codebase, try to load/integrate the tools instead.
An example is using `nvm`: Instead of copying the existing `nvm` script into Bash-it, the `nvm.plugin.bash` file tries to load an existing installation of `nvm`.
This means an additional step for the user (installing `nvm` from its own repo, or through a package manager),
but it will also ensure that `nvm` can be upgraded in an easy way.
## Themes
* When adding a new theme, please include a screenshot and a short description about what makes this theme unique in the Pull Request's description field. Please do not add theme screenshots to the repo itself, as they will add unnecessary bloat to the repo. The project's Wiki has a _Themes_ page where you can add a screenshot if you want.
* When adding a new theme, please include a screenshot and a short description about what makes this theme unique in the Pull Request's description field.
Please do not add theme screenshots to the repo itself, as they will add unnecessary bloat to the repo.
The project's Wiki has a _Themes_ page where you can add a screenshot if you want.
* Ideally, each theme's folder should contain a `README.md` file describing the theme and its configuration options.

145
README.md
View File

@ -2,37 +2,50 @@
[![Build Status](https://travis-ci.org/Bash-it/bash-it.svg?branch=master)](https://travis-ci.org/Bash-it/bash-it) [![Join the chat at https://gitter.im/Bash-it/bash-it](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/Bash-it/bash-it?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
**Bash-it** is a collection of community Bash commands and scripts for Bash 3.2+. (And a shameless ripoff of [oh-my-zsh](https://github.com/robbyrussell/oh-my-zsh) :smiley:)
**Bash-it** is a collection of community Bash commands and scripts for Bash 3.2+.
(And a shameless ripoff of [oh-my-zsh](https://github.com/robbyrussell/oh-my-zsh) :smiley:)
Includes autocompletion, themes, aliases, custom functions, a few stolen pieces from Steve Losh, and more.
Bash-it provides a solid framework for using, developing and maintaining shell scripts and custom commands for your daily work. If you're using the _Bourne Again Shell_ (Bash) on a regular basis and have been looking for an easy way on how to keep all of these nice little scripts and aliases under control, then Bash-it is for you! Stop polluting your `~/bin` directory and your `.bashrc` file, fork/clone Bash-it and start hacking away.
Bash-it provides a solid framework for using, developing and maintaining shell scripts and custom commands for your daily work.
If you're using the _Bourne Again Shell_ (Bash) on a regular basis and have been looking for an easy way on how to keep all of these nice little scripts and aliases under control, then Bash-it is for you!
Stop polluting your `~/bin` directory and your `.bashrc` file, fork/clone Bash-it and start hacking away.
## Contributing
Please take a look at the [Contribution Guidelines](CONTRIBUTING.md) before reporting a bug or providing a new feature.
The [Development Guidelines](DEVELOPMENT.md) have more information on some of the internal workings of Bash-it, please feel free to read through this page if you're interested in how Bash-it loads its components.
The [Development Guidelines](DEVELOPMENT.md) have more information on some of the internal workings of Bash-it,
please feel free to read through this page if you're interested in how Bash-it loads its components.
## Install
1. Check out a clone of this repo to a location of your choice, such as: `git clone --depth=1 https://github.com/Bash-it/bash-it.git ~/.bash_it`
1. Check out a clone of this repo to a location of your choice, such as:
`git clone --depth=1 https://github.com/Bash-it/bash-it.git ~/.bash_it`
2. Run `~/.bash_it/install.sh` (it automatically backs up your `~/.bash_profile` or `~/.bashrc`, depending on your OS)
3. Edit your modified config (`~/.bash_profile` or `~/.bashrc`) file in order to customize Bash-it.
4. Check out available aliases, completions and plugins and enable the ones you want to use (see the next section for more details).
**INSTALL OPTIONS:**
### INSTALL OPTIONS
The install script can take the following options:
* `--interactive`: Asks the user which aliases, completions and plugins to enable.
* `--silent`: Ask nothing and install using default settings.
* `--no-modify-config`: Do not modify the existing config file (`~/.bash_profile` or `~/.bashrc`).
When run without the `--interactive` switch, Bash-it only enables a sane default set of functionality to keep your shell clean and to avoid issues with missing dependencies. Feel free to enable the tools you want to use after the installation.
When run without the `--interactive` switch, Bash-it only enables a sane default set of functionality to keep your shell clean and to avoid issues with missing dependencies.
Feel free to enable the tools you want to use after the installation.
When you run without the `--no-modify-config` switch, the Bash-it installer automatically modifies/replaces your existing config file. Use the `--no-modify-config` switch to avoid unwanted modifications, e.g. if your Bash config file already contains the code that loads Bash-it.
When you run without the `--no-modify-config` switch, the Bash-it installer automatically modifies/replaces your existing config file.
Use the `--no-modify-config` switch to avoid unwanted modifications, e.g. if your Bash config file already contains the code that loads Bash-it.
**NOTE**: Keep in mind how Bash load its configuration files, `.bash_profile` for login shells (and in Mac OS X in terminal emulators like [Terminal.app](http://www.apple.com/osx/apps/) or [iTerm2](https://www.iterm2.com/)) and `.bashrc` for interactive shells (default mode in most of the GNU/Linux terminal emulators), to ensure that Bash-it is loaded correctly. A good "practice" is sourcing `.bashrc` into `.bash_profile` to keep things working in all the scenarios, to achieve this, you can add this snippet in your `.bash_profile`:
**NOTE**: Keep in mind how Bash load its configuration files,
`.bash_profile` for login shells (and in Mac OS X in terminal emulators like [Terminal.app](http://www.apple.com/osx/apps/) or
[iTerm2](https://www.iterm2.com/)) and `.bashrc` for interactive shells (default mode in most of the GNU/Linux terminal emulators),
to ensure that Bash-it is loaded correctly.
A good "practice" is sourcing `.bashrc` into `.bash_profile` to keep things working in all the scenarios.
To achieve this, you can add this snippet in your `.bash_profile`:
```
if [ -f ~/.bashrc ]; then
@ -63,13 +76,15 @@ bash-it update
that's all.
If you are using an older version of Bash-it, it's possible that some functionality has changed, or that the internal structure of how Bash-it organizes its functionality has been updated. For these cases, we provide a `migrate` command:
If you are using an older version of Bash-it, it's possible that some functionality has changed, or that the internal structure of how Bash-it organizes its functionality has been updated.
For these cases, we provide a `migrate` command:
```bash
bash-it migrate
```
This command will automatically migrate the Bash-it structure to the latest version. The `migrate` command is run automatically if you run the `update`, `enable` or `disable` commands.
This command will automatically migrate the Bash-it structure to the latest version.
The `migrate` command is run automatically if you run the `update`, `enable` or `disable` commands.
## Help Screens
@ -84,11 +99,8 @@ bash-it help plugins # shows help for installed plugins
## Search
If you need to quickly find out which of the plugins, aliases or completions
are available for a specific framework, programming language, or an environment, you can _search_ for
multiple terms related to the commands you use frequently. Search will
find and print out modules with the name or description matching the terms
provided.
If you need to quickly find out which of the plugins, aliases or completions are available for a specific framework, programming language, or an environment, you can _search_ for multiple terms related to the commands you use frequently.
Search will find and print out modules with the name or description matching the terms provided.
#### Syntax
@ -96,10 +108,8 @@ provided.
bash-it search term1 [[-]term2] [[-]term3]....
```
As an example, a ruby developer might want to enable everything
related to the commands such as `ruby`, `rake`, `gem`, `bundler` and `rails`.
Search command helps you find related modules, so that you can decide which
of them you'd like to use:
As an example, a ruby developer might want to enable everything related to the commands such as `ruby`, `rake`, `gem`, `bundler` and `rails`.
Search command helps you find related modules, so that you can decide which of them you'd like to use:
```bash
❯ bash-it search ruby rake gem bundle irb rails
@ -112,9 +122,9 @@ Currently enabled modules will be shown in green.
#### Search with Negations
You can prefix a search term with a "-" to exclude it from the results. In the above
example, if we wanted to hide `chruby` and `chruby-auto`, we could change the command as
follows:
You can prefix a search term with a "-" to exclude it from the results.
In the above example, if we wanted to hide `chruby` and `chruby-auto`,
we could change the command as follows:
```bash
❯ bash-it search ruby rake gem bundle irb rails -chruby
@ -125,15 +135,13 @@ follows:
#### Using Search to Enable or Disable Components
By adding a `--enable` or `--disable` to the search command, you can automatically
enable all modules that come up as a result of a search query. This could be quite
handy if you like to enable a bunch of components related to the same topic.
By adding a `--enable` or `--disable` to the search command, you can automatically enable all modules that come up as a result of a search query.
This could be quite handy if you like to enable a bunch of components related to the same topic.
#### Disabling ASCII Color
To remove non-printing non-ASCII characters responsible for the coloring of the
search output, you can set environment variable `NO_COLOR`. Enabled components will
then be shown with a checkmark:
To remove non-printing non-ASCII characters responsible for the coloring of the search output, you can set environment variable `NO_COLOR`.
Enabled components will then be shown with a checkmark:
```bash
❯ NO_COLOR=1 bash-it search ruby rake gem bundle irb rails -chruby
@ -154,11 +162,15 @@ For custom scripts, and aliases, just create the following files (they'll be ign
Anything in the custom directory will be ignored, with the exception of `custom/example.bash`.
Alternately, if you would like to keep your custom scripts under version control, you can set `BASH_IT_CUSTOM` in your `~/.bashrc` to another location outside of the `$BASH_IT` folder. In this case, any `*.bash` file under every directory below `BASH_IT_CUSTOM` folder will be used.
Alternately, if you would like to keep your custom scripts under version control, you can set `BASH_IT_CUSTOM` in your `~/.bashrc` to another location outside of the `$BASH_IT` folder.
In this case, any `*.bash` file under every directory below `BASH_IT_CUSTOM` folder will be used.
## Themes
There are over 50+ Bash-it themes to pick from in `$BASH_IT/themes`. The default theme is `bobby`. Set `BASH_IT_THEME` to the theme name you want, or if you've developed your own custom theme outside of `$BASH_IT/themes`, point the `BASH_IT_THEME` variable directly to the theme file.
There are over 50+ Bash-it themes to pick from in `$BASH_IT/themes`.
The default theme is `bobby`.
Set `BASH_IT_THEME` to the theme name you want, or if you've developed your own custom theme outside of `$BASH_IT/themes`,
point the `BASH_IT_THEME` variable directly to the theme file.
Examples:
@ -186,7 +198,8 @@ cd $BASH_IT
./uninstall.sh
```
This will restore your previous Bash profile. After the uninstall script finishes, remove the Bash-it directory from your machine (`rm -rf $BASH_IT`) and start a new shell.
This will restore your previous Bash profile.
After the uninstall script finishes, remove the Bash-it directory from your machine (`rm -rf $BASH_IT`) and start a new shell.
## Misc
@ -195,13 +208,17 @@ This will restore your previous Bash profile. After the uninstall script finishe
Bash-it creates a `reload` alias that makes it convenient to reload
your Bash profile when you make changes.
Additionally, if you export `BASH_IT_AUTOMATIC_RELOAD_AFTER_CONFIG_CHANGE` as a non-null value, Bash-it will automatically reload itself after activating or deactivating plugins, aliases, or completions.
Additionally, if you export `BASH_IT_AUTOMATIC_RELOAD_AFTER_CONFIG_CHANGE` as a non-null value,
Bash-it will automatically reload itself after activating or deactivating plugins, aliases, or completions.
### Prompt Version Control Check
Bash-it provides prompt themes the ability to check and display version control information for the current directory. The information is retrieved for each directory and can slow down the navigation of projects with a large number of files and folders. Turn version control checking off to prevent slow directory navigation within large projects.
Bash-it provides prompt themes the ability to check and display version control information for the current directory.
The information is retrieved for each directory and can slow down the navigation of projects with a large number of files and folders.
Turn version control checking off to prevent slow directory navigation within large projects.
Bash-it provides a flag (`SCM_CHECK`) within the `~/.bash_profile` file that turns off/on version control information checking and display within all themes. Version control checking is on by default unless explicitly turned off.
Bash-it provides a flag (`SCM_CHECK`) within the `~/.bash_profile` file that turns off/on version control information checking and display within all themes.
Version control checking is on by default unless explicitly turned off.
Set `SCM_CHECK` to 'false' to **turn off** version control checks for all themes:
@ -212,7 +229,9 @@ Set `SCM_CHECK` to 'true' (the default value) to **turn on** version control che
* `export SCM_CHECK=true`
**NOTE:**
It is possible for themes to ignore the `SCM_CHECK` flag and query specific version control information directly. For example, themes that use functions like `git_prompt_vars` skip the `SCM_CHECK` flag to retrieve and display git prompt information. If you turned version control checking off and you still see version control information within your prompt, then functions like `git_prompt_vars` are most likely the reason why.
It is possible for themes to ignore the `SCM_CHECK` flag and query specific version control information directly.
For example, themes that use functions like `git_prompt_vars` skip the `SCM_CHECK` flag to retrieve and display git prompt information.
If you turned version control checking off and you still see version control information within your prompt, then functions like `git_prompt_vars` are most likely the reason why.
### Git prompt
@ -222,7 +241,8 @@ Bash-it has some nice features related to Git, continue reading to know more abo
Bash-it can show some information about Git repositories in the shell prompt: the current branch, tag or commit you are at, how many commits the local branch is ahead or behind from the remote branch, and if you have changes stashed.
Additionally, you can view the status of your working copy and get the count of *staged*, *unstaged* and *untracked* files. This feature is controlled through the flag `SCM_GIT_SHOW_DETAILS` as follows:
Additionally, you can view the status of your working copy and get the count of *staged*, *unstaged* and *untracked* files.
This feature is controlled through the flag `SCM_GIT_SHOW_DETAILS` as follows:
Set `SCM_GIT_SHOW_DETAILS` to 'true' (the default value) to **show** the working copy details in your prompt:
@ -256,7 +276,11 @@ Set `SCM_GIT_SHOW_REMOTE_INFO` to 'false' to **disable the feature**:
#### Untracked files
By default, `git status` command shows information about *untracked* files, this behavior can be controlled through command line flags or git configuration files, for big repositories, ignoring *untracked* files can make git faster. Bash-it uses `git status` to gather the repo information it shows in the prompt, so in some circumstances, can be useful to instruct Bash-it to ignore these files. You can control this behavior with the flag `SCM_GIT_IGNORE_UNTRACKED`:
By default, the `git status` command shows information about *untracked* files.
This behavior can be controlled through command-line flags or git configuration files.
For big repositories, ignoring *untracked* files can make git faster.
Bash-it uses `git status` to gather the repo information it shows in the prompt, so in some circumstances, it can be useful to instruct Bash-it to ignore these files.
You can control this behavior with the flag `SCM_GIT_IGNORE_UNTRACKED`:
Set `SCM_GIT_IGNORE_UNTRACKED` to 'false' (the default value) to get information about *untracked* files:
@ -266,17 +290,24 @@ Set `SCM_GIT_IGNORE_UNTRACKED` to 'true' to **ignore** *untracked* files:
* `export SCM_GIT_IGNORE_UNTRACKED=true`
also, with this flag to false, Bash-it will not show the repository as dirty when the repo have *untracked* files, and will not display the count of *untracked* files.
Also, with this flag to false, Bash-it will not show the repository as dirty when the repo has *untracked* files, and will not display the count of *untracked* files.
**NOTE:** If you set in git configuration file the option to ignore *untracked* files, this flag has no effect, and Bash-it will ignore *untracked* files always.
#### Git user
In some environments it is useful to know the value of the current git user, which is used to mark all new commits. For example, any organization that uses the practice of pair programming will typically author each commit with a [combined names of the two authors](https://github.com/pivotal/git_scripts). When another pair uses the same pairing station, the authors are changed at the beginning of the session.
In some environments it is useful to know the value of the current git user, which is used to mark all new commits.
For example, any organization that uses the practice of pair programming will typically author each commit with a [combined names of the two authors](https://github.com/pivotal/git_scripts).
When another pair uses the same pairing station, the authors are changed at the beginning of the session.
To get up and running with this technique, run `gem install pivotal_git_scripts`, and then edit your `~/.pairs` file, according to the specification on the [gem's homepage](https://github.com/pivotal/git_scripts) After that you should be able to run `git pair kg as` to set the author to, eg. "Konstantin Gredeskoul and Alex Saxby", assuming they've been added to the `~/.pairs` file. Please see gem's documentation for more information.
To get up and running with this technique, run `gem install pivotal_git_scripts`, and then edit your `~/.pairs` file, according to the specification on the [gem's homepage](https://github.com/pivotal/git_scripts).
After that you should be able to run `git pair kg as` to set the author to, eg. "Konstantin Gredeskoul and Alex Saxby", assuming they've been added to the `~/.pairs` file.
Please see gem's documentation for more information.
To enable the display of the current pair in the prompt, you must set `SCM_GIT_SHOW_CURRENT_USER` to `true`. Once set, the `SCM_CURRENT_USER` variable will be automatically populated with the initials of the git author(s). It will also be included in the default git prompt. Even if you do not have `git pair` installed, as long as your `user.name` is set, your initials will be computed from your name, and shown in the prompt.
To enable the display of the current pair in the prompt, you must set `SCM_GIT_SHOW_CURRENT_USER` to `true`.
Once set, the `SCM_CURRENT_USER` variable will be automatically populated with the initials of the git author(s).
It will also be included in the default git prompt.
Even if you do not have `git pair` installed, as long as your `user.name` is set, your initials will be computed from your name, and shown in the prompt.
You can control the prefix and the suffix of this component using the two variables:
@ -290,7 +321,7 @@ And
#### Git show minimal status info
To speed up the prompt while still getting minimal git status information displayed such as the value of HEAD and whether there are any dirty objects, you can set:
To speed up the prompt while still getting minimal git status information displayed such as the value of `HEAD` and whether there are any dirty objects, you can set:
```
export SCM_GIT_SHOW_MINIMAL_INFO=true
@ -298,7 +329,8 @@ export SCM_GIT_SHOW_MINIMAL_INFO=true
#### Ignore repo status
When working in repos with a large code base Bash-it can slow down your prompt when checking the repo status, to avoid it, there is an option you can set via Git config to disable checking repo status in Bash-it.
When working in repos with a large codebase, Bash-it can slow down your prompt when checking the repo status.
To avoid it, there is an option you can set via Git config to disable checking repo status in Bash-it.
To disable checking the status in the current repo:
@ -312,11 +344,12 @@ But if you would like to disable it globally, and stop checking the status for a
$ git config --global --add bash-it.hide-status 1
```
setting this flag globally has the same effect that `SCM_CHECK=true` but only for Git repos.
Setting this flag globally has the same effect as `SCM_CHECK=true`, but only for Git repos.
### Pass function renamed to passgen
The Bash-it `pass` function has been renamed to `passgen` in order to avoid a naming conflict with the [pass password manager]. In order to minimize the impact on users of the legacy Bash-it `pass` function, Bash-it will create the alias `pass` that calls the new `passgen` function if the `pass` password manager command is not found on the `PATH` (default behavior).
The Bash-it `pass` function has been renamed to `passgen` in order to avoid a naming conflict with the [pass password manager](https://www.passwordstore.org/).
In order to minimize the impact on users of the legacy Bash-it `pass` function, Bash-it will create the alias `pass` that calls the new `passgen` function if the `pass` password manager command is not found on the `PATH` (default behavior).
This behavior can be overridden with the `BASH_IT_LEGACY_PASS` flag as follows:
@ -330,7 +363,9 @@ Unset `BASH_IT_LEGACY_PASS` to have Bash-it **return to default behavior**:
### Proxy Support
If you are working in a corporate environment where you have to go through a proxy server for internet access, then you know how painful it is to configure the OS proxy variables in the shell, especially if you are switching between environments, e.g. office (with proxy) and home (without proxy).
If you are working in a corporate environment where you have to go through a proxy server for internet access,
then you know how painful it is to configure the OS proxy variables in the shell,
especially if you are switching between environments, e.g. office (with proxy) and home (without proxy).
The Bash shell (and many shell tools) use the following variables to define the proxy to use:
@ -339,13 +374,16 @@ The Bash shell (and many shell tools) use the following variables to define the
* `ALL_PROXY` (and `all_proxy`): Used by some tools for the same purpose as above
* `NO_PROXY` (and `no_proxy`): Comma-separated list of hostnames that don't have to go through the proxy
Bash-it's `proxy` plugin allows to enable and disable these variables with a simple command. To start using the `proxy` plugin, run the following:
Bash-it's `proxy` plugin allows to enable and disable these variables with a simple command.
To start using the `proxy` plugin, run the following:
```bash
bash-it enable plugin proxy
```
Bash-it also provides support for enabling/disabling proxy settings for various shell tools. The following backends are currently supported (in addition to the shell's environment variables): Git, SVN, npm, ssh. The `proxy` plugin changes the configuration files of these tools to enable or disable the proxy settings.
Bash-it also provides support for enabling/disabling proxy settings for various shell tools.
The following backends are currently supported (in addition to the shell's environment variables): Git, SVN, npm, ssh.
The `proxy` plugin changes the configuration files of these tools to enable or disable the proxy settings.
Bash-it uses the following variables to set the shell's proxy settings when you call `enable-proxy`.
These variables are best defined in a custom script in Bash-it's custom script folder (`$BASH_IT/custom`), e.g. `$BASH_IT/custom/proxy.env.bash`
@ -357,13 +395,18 @@ Once you have defined these variables (and have run `reload` to load the changes
* `enable-proxy`: This sets the shell's proxy environment variables and configures proxy support in your SVN, npm and SSH configuration files.
* `disable-proxy`: This unsets the shell's proxy environment variables and disables proxy support in your SVN, npm and SSH configuration files.
There are many more proxy commands, e.g. for changing the local Git project's proxy settings. Run `glossary proxy` to show the available proxy functions with a short description.
There are many more proxy commands, e.g. for changing the local Git project's proxy settings.
Run `glossary proxy` to show the available proxy functions with a short description.
## Help out
We think everyone has their own custom scripts accumulated over time. And so, following in the footsteps of oh-my-zsh, Bash-it is a framework for easily customizing your Bash shell. Everyone's got a custom toolbox, so let's start making them even better, **as a community!**
We think everyone has their own custom scripts accumulated over time.
And so, following in the footsteps of oh-my-zsh, Bash-it is a framework for easily customizing your Bash shell.
Everyone's got a custom toolbox, so let's start making them even better, **as a community!**
Send us a pull request and we'll merge it as long as it looks good. If you change an existing command, please give an explanation why. That will help a lot when we merge your changes in.
Send us a pull request and we'll merge it as long as it looks good.
If you change an existing command, please give an explanation why.
That will help a lot when we merge your changes in.
Please take a look at the [Contribution Guidelines](CONTRIBUTING.md) before reporting a bug or providing a new feature.