Collapse

Not all files are created equally. Some are written by people with great care and effort while others are generated automatically.

pls can nest generated files under the handwritten ones when collapsing is enabled.

Preferences

CLI flags: --collapse/-c
Config YAML: collapse

This is a counter field. It can take any integer value.

  • Default: sets the collapse level to zero, turning off the collapsing functionality.

    $ pls # default
    $ pls -c 0
    
    prefs:
      collapse: 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: setting the collapse level to 1, nests the collapsed file beneath their parent.

    $ pls -c
    $ pls -c 1
    
    prefs:
      collapse: 1
    
   dist/                  
   readme_assets/         
   src/                   
   tests/                 
   CODE_OF_CONDUCT.md     
   CONTRIBUTING.md        
  .flake8                 
  .gitignore              
ﰌ   justfile               
   LICENSE                
  .pls.yml.pre-commit-config.yaml 
   pyproject.toml         
   └─ poetry.lockREADME.md              

Similarly, setting the collapse level to 2 (or above) hides collapsed files from the output altogether.

$ pls -c -c
$ pls -c 2
prefs:
  collapse: 1
   dist/                  
   readme_assets/         
   src/                   
   tests/                 
   CODE_OF_CONDUCT.md     
   CONTRIBUTING.md        
  .flake8                 
  .gitignore              
ﰌ   justfile               
   LICENSE                
  .pls.yml.pre-commit-config.yaml 
   pyproject.toml         
   README.md              

Configuration

Out of the box, pls can collapse the following files:

  • pyproject.toml
    • poetry.lock
  • Pipfile
    • Pipfile.lock
  • Gemfile
    • Gemfile.lock
  • package.json
    • package-lock.json
    • yarn.lock
    • pnpm-lock.yaml
  • file with extension ts
    • file with same name and extension js
  • file with extension tsx
    • file with same name and extension jsx
  • file with extension scss, sass or less
    • file with same name and extension css
   dist/                  
   readme_assets/         
   src/                   
   tests/.flake8                 
  .gitignore              
ﰌ   justfile               
   LICENSE                
  .pls.yml.pre-commit-config.yaml 
   pyproject.toml         
   └─ poetry.lock         
   README.md              

Notice how collapsing puts the poetry.lock file below pyproject.toml.

   index.html           
   package.json         
   └─ package-lock.json 
   scripts.ts           
   └─ scripts.js        
   styles.scss          
   └─ styles.css        

Notice how awesome collapse looks when there's a lot of content to work with.

Customisation

To define more collapse rules, 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 collapse rules for your projects (among other things).

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

Collapse rules are set via node specs. Refer to the docs for defining node specs.