colorls Documentation

CONTRIBUTING Copy Section

Contribution guidelines

First of all, thanks for thinking of contributing to this project. :smile:

Before sending a Pull Request, please make sure that you're assigned the task on a GitHub issue.

• If a relevant issue already exists, discuss on the issue and get it assigned to yourself on GitHub.
• If no relevant issue exists, open a new issue and get it assigned to yourself on GitHub.

Please proceed with a Pull Request only after you're assigned. It'd be sad if your Pull Request (and your hardwork) isn't accepted just because it isn't ideologically compatible.

Developing the gem

1. Install with

   sh Copy

   git clone https://github.com/athityakumar/colorls
   cd colorls
   gem install bundler
   bundle install

2. Make your changes in a different git branch (say, add-new-flag). These changes can be

   • adding better icons to YAML files
   • adding more flag options to the ruby gem.

3. (Optional) To test whether colorls executable is working properly, do

   sh Copy

   rake install

   Then install the gem file in the folder pkg. After that to use the new binary,

   sh Copy

   colorls # start using colorls

4. (Required for YAML file changes) These are the specifications for the YAML files -

   • files.yaml, folders.yaml : The keys are sorted alphabetically.
   • file_aliases.yaml, folder_aliases.yaml : The values are sorted alphabetically. For each set of keys mapping to a value, those set of keys are also sorted alphabetically.

5. Check before pushing

   sh Copy

   bundle exec rubocop
   bundle exec rspec

6. (Required for new flags) Add command to .travis.yml file.

7. (Required for new flags) Add flags to tab_complete.sh file.

README Copy Section

Color LS

A Ruby script that colorizes the ls output with color and icons. Here are the screenshots of working example on an iTerm2 terminal (Mac OS), oh-my-zsh with powerlevel9k theme and powerline nerd-font + awesome-config font with the Solarized Dark color theme.

If you're interested in knowing the powerlevel9k configuration to get this prompt, have a look at this gist.

Table of contents

• Usage
  • Flags
    • -1
    • -a (or) --all
    • -A (or) --almost-all
    • -d (or) --dirs
    • -f (or) --files
    • --help
    • -l (or) --long
    • --report
    • --tree (or) --tree=[DEPTH]
    • --gs (or) --git-status
    • --sd (or) --sort-dirs or --group-directories-first
    • --sf (or) --sort-files
    • -t
  • Combination of flags
• Installation
• Recommended configurations
• Custom configurations
• Updating
• Uninstallation
• Contributing
• License

Usage

(Back to top)

Man pages have been added. Checkout man colorls.

Flags Copy Section

• With -1 : Lists one entry per line

• With -a (or) --all : Does not ignore entries starting with '.'

• With -A (or) --almost-all : Does not ignore entries starting with '.', except ./ and ../

• With -d (or) --dirs : Shows only directories

• With -f (or) --files : Shows only files

• With --help : Prints a very helpful help menu

• With -l (or) --long : Shows in long listing format

• With --report : Shows brief report about number of files and folders shown

• With --tree (or) --tree=[DEPTH] : Shows tree view of the directory with the specified depth (default 3)

• With --gs (or) --git-status : Shows git status for each entry

• With --sd (or) --sort-dirs or --group-directories-first : Shows directories first, followed by files

• With --sf (or) --sort-files : Shows files first, followed by directories

• With -t : Sort by modification time, newest first (NEED TO ADD IMAGE)

• With color options : --light or --dark can be passed as a flag, to choose the appropriate color scheme. By default, the dark color scheme is chosen. In order to tweak any color, read Custom configurations.

Combination of flags Copy Section

• Using --gs with -t :

• Using --gs with -l :

• Using --sd with -l and -A :

• Using --non-human-readable with -l :

  • This will print the file sizes in bytes (non-human readable format)

Installation

(Back to top)

1. Install Ruby (preferably, version >= 2.6 via a version manager like rbenv)

2. Download and install a Nerd Font so you can see the library icons. Have a look at the Nerd Font README for installation instructions. We're using "Hack Nerd Font" for this guide.

   Note for MacOS users using the stock terminal - Please enable Nerd Font at Terminal > Preferences > Profiles > Text > Font. Click Change.. and select Hack Nerd Font - Regular

   Note for iTerm2 users - Please enable the Nerd Font at iTerm2 > Preferences > Profiles > Text > Non-ASCII font > Hack Regular Nerd Font Complete.

   Note for HyperJS users - Please add "Hack Nerd Font" Font as an option to fontFamily in your ~/.hyper.js file.

3. Install the colorls ruby gem with gem install colorls

   Note for rbenv users - In case of load error when using lc, please try the below patch.

   sh Copy

   rbenv rehash
   rehash

4. Enable tab completion for flags by entering following line to your shell configuration file (~/.bashrc or ~/.zshrc) :

   bash Copy

   source $(dirname $(gem which colorls))/tab_complete.sh

   Don't forget to restart your terminal

5. Start using colorls :tada:

6. Have a look at Recommended configurations and Custom configurations.

If you're having trouble following the installation guide above, here's a video reproducing steps 2 to 6.

Recommended configurations

(Back to top)

1. To add some short command (say, lc) with some flag options (say, -l, -A, --sd) by default, add this to your shell configuration file (~/.bashrc, ~/.zshrc, etc.) :

   sh Copy

   alias lc='colorls -lA --sd'

2. For changing the icon(s) to other unicode icons of choice (select icons from here), change the YAML files in a text editor of your choice (say, subl)

   sh Copy

   subl $(dirname $(gem which colorls))/yaml

Custom configurations

(Back to top)

You can overwrite the existing icons and colors mapping by copying the yaml files from $(dirname $(gem which colorls))/yaml into ~/.config/colorls, and changing them.

• To overwrite color mapping :

  Please have a look at the list of supported color names. You may also use a color hex code as long as it is quoted within the YAML file and prefaced with a # symbol.

  Let's say that you're using the dark color scheme and would like to change the color of untracked file (??) in the --git-status flag to yellow. Copy the defaut dark_colors.yaml and change it.

  Check if the ~/.config/colorls directory exists. If it doesn't exist, create it using the following command:

  sh Copy

  mkdir -p ~/.config/colorls

  And then

  sh Copy

  cp $(dirname $(gem which colorls))/yaml/dark_colors.yaml ~/.config/colorls/dark_colors.yaml

  In the ~/.config/colorls/dark_colors.yaml file, change the color set for untracked from darkorange to yellow, and save the change.

  text Copy

  untracked: yellow

  Or, using hex color codes:

  text Copy

  untracked: '#FFFF00'

• To overwrite icon mapping :

  Please have a look at the list of supported icons. Let's say you want to add an icon for swift files. Copy the default files.yaml and change it.

  sh Copy

  cp $(dirname $(gem which colorls))/yaml/files.yaml ~/.config/colorls/files.yaml`

  In the ~/.config/colorls/files.yaml file, add a new icon / change an existing icon, and save the change.

  text Copy

  swift: "\uF179"

• User contributed alias configurations :

  • @rjhilgefort

Updating

(Back to top)

Want to update to the latest version of colorls?

gem update colorls

Uninstallation

(Back to top)

Want to uninstall and revert back to the old style? No issues (sob). Please feel free to open an issue regarding how we can enhance colorls.

gem uninstall colorls

Contributing

(Back to top)

Your contributions are always welcome! Please have a look at the contribution guidelines first. :tada:

License

(Back to top)

The MIT License (MIT) 2017 - Athitya Kumar. Please have a look at the LICENSE.md for more details.