HomeSetup

Your shell, good as hell !

HomeSetup is a bundle of scripts and dotfiles that will elevate your bash shell experience to another level. There are many improvements and facilities, especially for developers that will ease the usage and highly improve your productivity. Currently we support Bash (v3.4+) for Darwin (MacOS) and Linux. We have plans to add support for Zsh as well.

THIS IT NOT JUST ANOTHER DOTFILES FRAMEWORK

LINUX IS HERE

Highlights

HomeSetup was created to help users with the command line. The purpose was to create useful and easy-to-use features that speedup daily tasks such as, punching the clock, searching for strings and files, change directories, using git, gradle, docker, etc...

• Setup most common used configurations automatically.
• New <tab+shift> complete (using menu-complete) that will cycle though options.
• Prompt with a mono-spaced font that supports Font-Awesome icons.
• Package manager helper to help installing application using recipes (not only brew installs).
• Save your custom dotfiles on a Firebase and download it wherever you go.
• New visual way to select, choose and input data for your scripts (pure bash code).
• Dozens of functions to help you configure your terminal and deal with your daily tasks.
• Highly customizable aliases, so, you dictate what mnemonics you want to use (use your own syntax).
• All code is licensed under The MIT License, so, you can modify and use freely.
• Small learning curve and a complete User's Handbook.
• NEW HomeSetup now works on Linux as well.
• NEW Try HomeSetup on a docker container before installing on your machine.

Catalina moved from bash to zsh

Latest version of MacOS comes with zsh as the default shell, but you can change it at any time with the following command:

$ sudo chsh -s /bin/bash

If apple decides to remove from next MacOS releases, you can always use Home-Brew's version. In this case, the path is different:

$ brew install bash
$ sudo chsh -s /usr/local/bin/bash

Table of contents

• 1. Installation
  • 1.1. Requirements
    • 1.1.1. Operating systems
    • 1.1.1. Supported Shells
    • 1.1.2. Required software
      • 1.1.2.1. Darwin and Linux
      • 1.1.2.2. Darwin only
    • 1.1.3. Recommended software
    • 1.1.4. Optional software
    • 1.1.5. Terminal setup
      • 1.1.5.1. Terminal App
      • 1.1.5.2. iTerm2 App
  • 1.1. Try-it first
  • 1.2. Remote installation
  • 1.3. Local installation
  • 1.4. Firebase setup
    • 1.4.1. Create account
    • 1.4.2. Configure account
• 2. Uninstallation
• 3. Usage
• 4. Dotfiles in this project
• 5. Aliases
  • 5.1. Navigational
  • 5.2. General
  • 5.3. HomeSetup
  • 5.4. Tool aliases
  • 5.5. OS Specific aliases
    • 5.5.1. Linux
    • 5.5.2. Darwin
  • 5.6. Handy terminal shortcuts
  • 5.7. Python aliases
  • 5.8. Perl aliases
  • 5.9. Git aliases
  • 5.10. Gradle aliases
  • 5.11. Docker aliases
• 6. Functions
  • 6.1. Standard tools
  • 6.2. Development tools
• 7. Applications
  • 7.1. Bash apps
  • 7.2. Python apps
• 8. Alias Definitions
• 9. HomeSetup application
  • 9.1. Plug-ins
  • 9.2. Functions
• 10. Auto completions
  • 10.1. Bash completions
• 12. Contact
• 13. Support HomeSetup
• 14. Final notes

Installation

Requirements

Operating Systems

• Darwin
  • High Sierra and higher
• Linux
  • Ubuntu 16 and higher
  • CentOS 7 and higher
  • Fedora 31 and higher

You may want to install HomeSetup on other linux distributions and it will probably work, but there are no guarantees that it WILL ACTUALLY WORK .

Supported Shells

• Bash: Everything from 3.2.57(1) and higher.
• Zsh: Zsh is not supported yet.

Required software

The following software are required either to clone the repository, execute the tests and install packages:

Darwin and Linux

• git v2.20+ : To clone and maintain the code.
• curl v7.64+ : To make http(s) requests.
• python v2.7+ or v3.0+ : To run python based scripts.
• gpg v2.2+: : To enable encryption based functions.

Darwin only

• brew v2.0+ : To install the required tools.
• xcode-select v2373+: To install command line tools.

Recommended software

HomeSetup depends on a series of tools. To use some of the features of HomeSetup, the following packages are required:

• bats v0.4+ : To run the automated tests.
• perl v5.0+ : To enable perl based functions.
• dig v9.10+ : To enable networking functions.
• tree v1.8+ : To enable directory visualization functions.
• ifconfig v8.43+ : To enable networking functions.

Optional software

There are some tools that are also good to have if you are a developer, HomeSetup provides features to improve using the following tools:

• docker 19.03+ : To enable docker functions.
• gradle 4+ : To enable gradle functions.

Terminal setup

HomeSetup requires a font that supports Font-Awesome icons. We suggest you to use the one we provide:

• Droid font.

You need to install it on your machine before installing or trying HomeSetup, otherwise, you will see a question mark icon instead of the real icons.

Mac users: We suggest a terminal profile to use (see the below topics).

Linux users: We have checked that some terminals already support icons, if not, you can install it manually.

Terminal App (Darwin)

• Import the HomeSetup-(14|15)-inch.terminal from "$HHS_HOME/misc" to your Terminal App.
• Set HomeSetup as the default profile.

iTerm2 App (Darwin)

• Import the iterm2-terminal-(14|15)-inch.json from "$HHS_HOME/misc" to your iTerm2 App.
• Set HomeSetup as the default profile.

Try-it first

You can run HomeSetup from a docker container and then decide whether to install it on your machine. To do that, you need to pull the image you want to try:

$ docker run --rm -it yorevs/hhs-centos

or

$ docker run --rm -it yorevs/hhs-ubuntu

or

$ docker run --rm -it yorevs/hhs-fedora

Remote installation

This is the recommended installation type. You can install HomeSetup directly from GitHub. To do that use the following command to clone and install:

$ curl -o- https://raw.githubusercontent.com/yorevs/homesetup/master/install.bash | bash

or

$ wget -qO- https://raw.githubusercontent.com/yorevs/homesetup/master/install.bash | bash

Local installation

Clone the repository using the following command:

$ git clone https://github.com/yorevs/homesetup.git ~/HomeSetup

And then install dotfiles using the following command:

$ cd ~/HomeSetup && ./install.bash => To install all files

or

$ cd ~/HomeSetup && ./install.bash -i => To install one by one

Your old dotfiles (.bash*) will be backed up using '.orig' suffix and sent to ~/.hhs folder.

Firebase setup

HomeSetup allows you to use your Firebase account to upload and download your custom files (dotfiles files synchronization) to your Real-time Database. To be able to use this feature, you need first to configure your Google Firebase account.

Create new account

If you have a Google account but do not have a Firebase one, you can do that using your Google credentials.

Access: https://console.firebase.google.com/

1. Create a new Project (HomeSetup).
2. Create Database (as production mode).
   • Click on Develop -> Database -> Create Database
   • Click on Real-time Database
   • Click on the Rules tab.
     • Change the line from: ".read": false, to ".read": true,.
     • Change the line from: ".write": false, to ".write": true,.
     • Click on the Publish button and accept changes.

Configure account

In order to use your Firebase account with HomeSetup, you will need to configure the read and write permissions as showed on topic 1.3.1..

Access your account from: https://console.firebase.google.com/

Grab you Project ID from the settings Settings menu.

Type in a shell: $ dotfiles --setup

Fill in the information required. You are now ready to use the Firebase features of HomeSetup. Type: $ dotfiles.bash help fb for further information about using it.

Uninstallation

If you decide to, you can uninstall all HomeSetup files and restore your old dotfiles. To do that issue the command in a shell: # HomeSetup> ./uninstall.bash

The uninstaller will remove all files and folders related to HomeSetup for good. The only folder that will stay is the ~/.hhs where your configurations were stored. It's safe to delete this folder after the uninstallation of HomeSetup.

Usage

HomeSetup provides a User Handbook with all commands and examples of usage. There will also be a video about how to install, configure and all available features demo.

Dotfiles in this project

The following files will be added when installing this project:

~/.bashrc # Bash resources init
~/.bash_profile # Profile bash init
~/.bash_aliases # All defined aliases
~/.bash_prompt # Enhanced shell prompt
~/.bash_env # Environment variables
~/.bash_colors # All defined color related stuff
~/.bash_functions # Scripting functions

The following directory will be linked to your HOME folder:

~/bin # Includes all useful script provided by the project

If this folder already exists, the install script will copy all files into it.

To override or add customized stuff, you need to create a custom file as follows:

~/.colors           : To customize your colors
~/.env              : To customize your environment variables
~/.aliases          : To customize your aliases
~/.prompt           : To customize your prompt
~/.functions        : To customize your functions
~/.profile          : To customize your profile
~/.path             : To customize your paths
~/.aliasdef         : To customize your alias definitions

Aliases

HomeSetup will provide many useful aliases (shortcuts) to your terminal:

Navigational

General

HomeSetup (HHS)

Tool aliases

OS Specific aliases

Linux

Darwin

Handy Terminal Shortcuts

Python aliases

Perl aliases

Git aliases

Gradle aliases

Docker aliases

Functions

HomeSetup provides many functions for the shell. All functions includes a help using the options -h or --help.

Standard tools

The complete handbook of standard tools can be found on the functions handbook

Development tools

The complete handbook of development tools can be found here

Applications

HomeSetup provides useful applications that can be used directly from shell. It is also added to your PATH variable. The complete handbook of development tools can be found here

Bash apps

Python apps

Alias definitions

You can customize most of HomeSetup aliases by editing your file ~/.aliasdef. When you first install HomeSetup, this file will be automatically generated for you. Further updates may require this file to be updated. We always keep a backup of this file, so, you can preserve your customizations, but this process has to be manual.

The original content and aliases are defined on the original aliasdef file.

HomeSetup Application

HomeSetup application is a bundle of scripts and functions to extend the terminal features. There are plug-able scripts and functions to be incorporated into the app.

HHS plugins

HHS functions

Auto completions

In addition to the normal bash complete, HomeSetup comes with another <shift+tab> complete. With this, you can iterate over the options provided by the complete function instead of just displaying them.

Bash completions

Contact

You can contact us using our Gitter community or using our Reddit.

Support HomeSetup

You can support HomeSetup by donating or coding. Fell free to contact me for details. When contributing with code change please take a look at our guidelines and code of conduct.

Final notes

HomeSetup will fetch for update automatically every 7 days from the installation on.

To manually keep your HomeSetup updated, run $ hhs updater execute. This will install the latest HomeSetup version.