Importance

Not all files and folders in a directory are equally important. This is especially true for modern software development, where the root folder of a project is filled with scaffolding and configuration files for toolchains.

pls uses an importance scale that it makes it easy to find your proverbial needle in the haystack. The importance of files decides whether files are shown and controls their visual prominence.

Preferences

CLI flags: --all/-a
Config YAML: all

This is a counter field. It can take any integer value. See the field documentation for usage.

  • Default: sets the importance threshold to zero, so files with importance -1 are dimmed and those with importance -2 or lower are invisible.

    $ pls # default
    $ pls -a 0
    
    prefs:
      all: 0
    
   dist/                  
   readme_assets/         
   src/                   
   tests/                 
   CODE_OF_CONDUCT.md     
   CONTRIBUTING.md        
  .flake8                 
  .gitignore              
ﰌ   justfile               
   LICENSE                
  .pls.yml                
   poetry.lock.pre-commit-config.yaml 
   pyproject.toml         
   README.md              
  • Custom: to see files with importance -2 as dimmed and importance -1 as regular files, lower the threshold by 1.

    $ pls -a
    $ pls -a 1
    
    prefs:
      all: 1
    
   dist/                  
  .git/                   
  .github/                
  .idea/                  
  .mypy_cache/            
  .pytest_cache/          
   readme_assets/         
   src/                   
   tests/                 
  .vscode/                
   CODE_OF_CONDUCT.md     
   CONTRIBUTING.md        
   .coverage               
  .DS_Store.flake8                 
  .gitignore              
ﰌ   justfile               
   LICENSE                
  .pls.yml                
   poetry.lock.pre-commit-config.yaml 
   pyproject.toml         
   README.md              

Similarly, to see files with importance -3 as dimmed and importance -1 and -2 as regular files, lower the threshold by 2.

$ pls -a -a
$ pls -a 2
prefs:
  all: 2

Configuration

Out of the box, pls configures an importance of -1 for the autogenerated code such as lockfiles for package managers.

  • Python

    • poetry.lock
    • Pipfile.lock
    • env/
    • venv/
  • JavaScript

    • package-lock.json
    • yarn.lock
    • pnpm-lock.yaml
    • node_modules/
  • Ruby

    • Gemfile.lock
    • vendor
    • bundle

Some especially useless files are bestowed the importance of -2.

  • .DS_Store

  • Python

    • __pycache__

Customisation

To configure file importance, you can do either of the following.

  • Extend the configuration locally using a local .pls.yml file.
    For the majority of use cases, this is the preferred option. Using pls's powerful extensibility, you can define the importance of the files and folders inside your projects (among other things).

  • Make a pull-request to pls.
    This only applies if the file type is fairly common and the inclusion of the config adds value for a lot of developers. The pls OOBE is intentionally minimal.

Importance levels are set via node specs. Refer to the docs for defining node specs.

Reference

The importance of files is classified into 5 levels.

LevelSignificanceAppearance
-2Least importantHidden by default
-1Lower importanceDimmed
0Neutral importanceNormal
+1Higher importanceBold
+2Most importantUnderline

If any spec sets the importance of a file, it takes precedence over the default. The default importance of a file is determined on the basis of two factors:

  • whether the file has any spec associated with it
  • whether the file name starts with a leading dot .
Has specLeading .Default importance
NoNo0
YesNo0
NoYes-2
YesYes-1

Files without a leading dot have a default importance of 0. Files with a leading dot have importance -1 if they have a matching spec or -2 if they don't.