Filtering

When looking for files, filtering is one of the powerful tools in your arsenal. pls can filter files using a number of techniques, including the most powerful of them all, regular expressions.

By type

pls allows you to selectively filter out directories or files from the output.

Files

CLI flags: --files/--no-files
Config YAML: files

This is a boolean field.

• --files/true: show files in the output (default)

  $ pls # default
  $ pls --files
  

  prefs:
    files: true
  

• --no-files

  $ pls --no-files
  

  prefs:
    files: false
  

   readme_assets/ 
   src/           
ﭧ   tests/         

Directories

CLI flags: --dirs/--no-dirs
Config YAML: dirs

This is a boolean field.

• --dirs/true: show directories in the output (default)

  $ pls # default
  $ pls --dirs
  

  prefs:
    files: true
  

• --no-dirs

  $ pls --no-dirs
  

  prefs:
    dirs: false
  

   CODE_OF_CONDUCT.md     
   CONTRIBUTING.md        
  .flake8                 
  .gitignore              
ﰌ   justfile               
   LICENSE                
  .pls.yml                
   poetry.lock            
  .pre-commit-config.yaml 
   pyproject.toml         
   README.md              

By name

There are a number of flags that control the filter criteria.

Exclude

CLI flags: --exclude/-e
Config YAML: exclude

This is a string field.

Pass the --exclude/-e option with a regular expression to hide all files matching the pattern.

$ pls -e '.*\.ya?ml'

prefs:
  exclude: .*\.ya?ml

   readme_assets/     
   src/               
ﭧ   tests/             
   CODE_OF_CONDUCT.md 
   CONTRIBUTING.md    
  .flake8             
  .gitignore          
ﰌ   justfile           
   LICENSE            
   poetry.lock        
   pyproject.toml     
   README.md          

Include

CLI flags: --only/-o
Config YAML: only

This is a string field.

Pass the --only/-o option with a regular expression to only show files matching the pattern.

$ pls -o '.*\.ya?ml'

prefs:
  only: .*\.ya?ml

  .pls.yml                
  .pre-commit-config.yaml 

Reference

Both the exclude and only options take regular expressions that are matched against the node name. The match is performed from the start of the node name so for matches targeting substrings not in the beginning should be prefixed with a wildcard match at the start .*.

WARNING

Filters are combined by AND operations. Thus, setting both only and exclude (either via CLI or YAML config) will lead to a combined effect where only files and directories satisfying both conditions will be shown.

TIP

In the CLI, wrap the regular expression in single quotes to prevent the shell from tampering with it. In YAML, skip the quotes altogether or use single quotes to prevent the escape codes from being parsed.

$ pls -e 'README' -o '.*\.md'

prefs:
  exclude: README
  only: .*\.md

   CODE_OF_CONDUCT.md 
   CONTRIBUTING.md    

By importance

See the docs for the Importance feature for more information on this filtering option.