ls-lint

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ls-lint v2.3

Version Notice: This skill documents ls-lint v2.3 specifically. Before proceeding, verify the installed version matches:
bash
ls-lint --version
# or
npx @ls-lint/ls-lint --version
If a different version is installed, stop and consult the official documentation for that version at https://ls-lint.org or the GitHub repository at https://github.com/loeffel-io/ls-lint. Configuration syntax and available rules may differ between versions.

An extremely fast directory and filename linter that enforces naming conventions across project filesystems.

Official Resources:

GitHub: https://github.com/loeffel-io/ls-lint
Documentation: https://ls-lint.org/2.3/getting-started/introduction.html

Key features:

Processes thousands of files in milliseconds
Minimal configuration via
```
.ls-lint.yml
```
Cross-platform: Windows, macOS, Linux
Full Unicode support
Minimal dependencies (go-yaml, doublestar)

版本说明： 本Skill专门针对ls-lint v2.3版本编写。开始操作前，请确认已安装的版本是否匹配：
bash
ls-lint --version
# 或
npx @ls-lint/ls-lint --version
如果安装的是其他版本，请停止操作并查阅对应版本的官方文档，地址为https://ls-lint.org或GitHub仓库https://github.com/loeffel-io/ls-lint。不同版本的配置语法和可用规则可能存在差异。

这是一款极速的目录与文件名检查工具，可在项目文件系统中强制统一命名规范。

官方资源：

GitHub：https://github.com/loeffel-io/ls-lint
官方文档：https://ls-lint.org/2.3/getting-started/introduction.html

核心特性：

毫秒级处理数千个文件
通过
```
.ls-lint.yml
```
实现极简配置
跨平台支持：Windows、macOS、Linux
完整Unicode支持
依赖极少（仅go-yaml、doublestar）

Installation

安装

bash

undefined

bash

undefined

NPM (recommended)

NPM（推荐方式）

npm install -D @ls-lint/ls-lint

NPX (no install)

NPX（无需安装）

npx @ls-lint/ls-lint

Homebrew (macOS/Linux)

Homebrew（macOS/Linux）

brew install ls-lint

Direct download (Linux amd64)

直接下载（Linux amd64）

curl -sL -o ls-lint https://github.com/loeffel-io/ls-lint/releases/download/v2.3.1/ls-lint-linux-amd64 chmod +x ls-lint

undefined

curl -sL -o ls-lint https://github.com/loeffel-io/ls-lint/releases/download/v2.3.1/ls-lint-linux-amd64 chmod +x ls-lint

undefined

Configuration Basics

配置基础

Create

.ls-lint.yml

in the project root with two main sections:

yaml

ls:
  # Rules for directories and file extensions
  .js: kebab-case
  .ts: kebab-case

ignore:
  # Paths to exclude from linting
  - .git
  - node_modules

在项目根目录创建

.ls-lint.yml

文件，包含两个核心部分：

yaml

ls:
  # 针对目录和文件扩展名的规则
  .js: kebab-case
  .ts: kebab-case

ignore:
  # 排除检查的路径
  - .git
  - node_modules

Running ls-lint

运行ls-lint

bash

undefined

bash

undefined

Run with default config (.ls-lint.yml)

使用默认配置文件（.ls-lint.yml）运行

npx @ls-lint/ls-lint

Custom config path

指定自定义配置文件路径

ls-lint --config path/to/.ls-lint.yml

Custom working directory

指定自定义工作目录

ls-lint --workdir /path/to/project

undefined

ls-lint --workdir /path/to/project

undefined

Built-in Rules

内置规则

Six naming convention rules are available:

Rule	Description	Example
`lowercase`	All lowercase letters, ignores non-letters	`readme` , `test`
`camelCase`	camelCase, letters and digits only	`myFile`
`PascalCase`	PascalCase, letters and digits only	`MyComponent`
`snake_case`	Lowercase with underscores	`my_file`
`SCREAMING_SNAKE_CASE`	Uppercase with underscores	`MY_CONSTANT`
`kebab-case`	Lowercase with hyphens	`my-file`

提供六种命名规范规则：

规则	描述	示例
`lowercase`	全小写字母，忽略非字母字符	`readme` 、 `test`
`camelCase`	小驼峰命名，仅允许字母和数字	`myFile`
`PascalCase`	大驼峰命名，仅允许字母和数字	`MyComponent`
`snake_case`	小写字母加下划线分隔	`my_file`
`SCREAMING_SNAKE_CASE`	大写字母加下划线分隔	`MY_CONSTANT`
`kebab-case`	小写字母加连字符分隔	`my-file`

Combining Rules

组合规则

Use the pipe operator

to allow multiple conventions:

yaml

ls:
  .ts: camelCase | PascalCase   # Either is valid
  .js: kebab-case | snake_case

使用管道符

允许同时应用多种命名规范：

yaml

ls:
  .ts: camelCase | PascalCase   # 两种规范均有效
  .js: kebab-case | snake_case

Extensions & Sub-extensions

扩展名与子扩展名

Standard Extensions

标准扩展名

Apply rules to specific file types:

yaml

ls:
  .js: kebab-case
  .ts: kebab-case
  .json: kebab-case
  .md: SCREAMING_SNAKE_CASE   # README.md, CHANGELOG.md

为特定文件类型应用规则：

yaml

ls:
  .js: kebab-case
  .ts: kebab-case
  .json: kebab-case
  .md: SCREAMING_SNAKE_CASE   # README.md、CHANGELOG.md

Sub-extensions

子扩展名

Handle compound extensions like

.d.ts

.test.js

.module.css

yaml

ls:
  .d.ts: kebab-case           # Type definition files
  .test.ts: kebab-case        # Test files
  .module.css: kebab-case     # CSS modules
  .config.js: kebab-case      # Config files

处理复合扩展名，如

.d.ts

、

.test.js

、

.module.css

：

yaml

ls:
  .d.ts: kebab-case           # TypeScript类型定义文件
  .test.ts: kebab-case        # 测试文件
  .module.css: kebab-case     # CSS模块
  .config.js: kebab-case      # 配置文件

Wildcard Extension

通配符扩展名

Match all extensions with

.*

yaml

ls:
  .*: kebab-case              # All files must be kebab-case

使用

.*

匹配所有扩展名：

yaml

ls:
  .*: kebab-case              # 所有文件必须使用kebab-case命名

Directory Naming

目录命名规则

Use

.dir

to enforce directory name conventions:

yaml

ls:
  .dir: kebab-case            # All directories must be kebab-case

使用

.dir

强制目录命名规范：

yaml

ls:
  .dir: kebab-case            # 所有目录必须使用kebab-case命名

Path Patterns

路径模式

Global Rules

全局规则

Rules at the top level apply project-wide:

yaml

ls:
  .js: kebab-case             # Applies everywhere
  .ts: kebab-case

ignore:
  - node_modules

顶层规则将应用于整个项目：

yaml

ls:
  .js: kebab-case             # 全局生效
  .ts: kebab-case

ignore:
  - node_modules

Directory-Specific Rules

目录特定规则

Override global rules for specific directories:

yaml

ls:
  .js: kebab-case             # Global default

  components:                 # Override for components/
    .js: PascalCase

  src/models:                 # Override for src/models/
    .js: PascalCase

Directory rules apply to the specified directory and all its subdirectories.

为特定目录覆盖全局规则：

yaml

ls:
  .js: kebab-case             # 全局默认规则

  components:                 # 覆盖components/目录下的规则
    .js: PascalCase

  src/models:                 # 覆盖src/models/目录下的规则
    .js: PascalCase

Glob Patterns

通配符模式

Use wildcards for flexible path matching:

yaml

ls:
  # Single wildcard: matches one directory level
  packages/*/src:
    .ts: kebab-case

  # Double wildcard: matches any depth
  packages/**/components:
    .tsx: PascalCase

使用通配符实现灵活的路径匹配：

yaml

ls:
  # 单通配符：匹配一级目录
  packages/*/src:
    .ts: kebab-case

  # 双通配符：匹配任意层级目录
  packages/**/components:
    .tsx: PascalCase

Alternative Patterns

多选项模式

Use curly braces for multiple alternatives:

yaml

ls:
  packages/*/{src,tests}:
    .ts: kebab-case

  src/{components,pages}:
    .tsx: PascalCase

使用大括号指定多个可选路径：

yaml

ls:
  packages/*/{src,tests}:
    .ts: kebab-case

  src/{components,pages}:
    .tsx: PascalCase

Advanced Rules

高级规则

Regex Patterns

正则表达式模式

For custom naming patterns, use regex with

regex:^pattern$

format:

yaml

ls:
  # Files must start with uppercase letter
  .ts: regex:^[A-Z].*$

  # Allow files starting with underscore or letter
  .js: regex:^[_a-z][a-zA-Z0-9]*$

Combine regex with built-in rules:

yaml

ls:
  .ts: PascalCase | regex:^index$   # PascalCase OR "index"

如需自定义命名模式，使用

regex:^pattern$

格式：

yaml

ls:
  # 文件必须以大写字母开头
  .ts: regex:^[A-Z].*$

  # 允许以下划线或小写字母开头的文件
  .js: regex:^[_a-z][a-zA-Z0-9]*$

可将正则规则与内置规则组合使用：

yaml

ls:
  .ts: PascalCase | regex:^index$   # 允许PascalCase命名或文件名是"index"

Directory Substitution

目录替换

Reference parent directory names in patterns:

yaml

ls:
  # File must match parent directory name
  components/*/:
    .tsx: regex:^${0}$   # ${0} = parent directory name

在模式中引用父目录名称：

yaml

ls:
  # 文件名必须与父目录名称一致
  components/*/:
    .tsx: regex:^${0}$   # ${0} 代表父目录名称

Exists Rule

存在性规则

Enforce file quantity constraints:

yaml

ls:
  # Exactly one index file required
  src/:
    index.ts: exists:1

  # Between 1-5 test files allowed
  tests/:
    .test.ts: exists:1-5

  # No image files allowed
  src/:
    .png: exists:0
    .jpg: exists:0

Combine with naming rules:

yaml

ls:
  .ts: kebab-case | exists:1   # Must be kebab-case AND exactly one

强制约束文件数量：

yaml

ls:
  # 必须存在且仅存在一个index文件
  src/:
    index.ts: exists:1

  # 允许存在1-5个测试文件
  tests/:
    .test.ts: exists:1-5

  # 不允许存在图片文件
  src/:
    .png: exists:0
    .jpg: exists:0

可与命名规则组合使用：

yaml

ls:
  .ts: kebab-case | exists:1   # 必须使用kebab-case命名且仅存在一个

Common Configurations

常见配置示例

JavaScript/TypeScript Project

JavaScript/TypeScript项目

yaml

ls:
  .dir: kebab-case
  .js: kebab-case
  .ts: kebab-case
  .tsx: PascalCase           # React components
  .d.ts: kebab-case
  .json: kebab-case
  .md: SCREAMING_SNAKE_CASE

  src/components:
    .tsx: PascalCase

ignore:
  - .git
  - node_modules
  - dist
  - coverage

yaml

ls:
  .dir: kebab-case
  .js: kebab-case
  .ts: kebab-case
  .tsx: PascalCase           # React组件
  .d.ts: kebab-case
  .json: kebab-case
  .md: SCREAMING_SNAKE_CASE

  src/components:
    .tsx: PascalCase

ignore:
  - .git
  - node_modules
  - dist
  - coverage

Monorepo Pattern

单仓库多项目（Monorepo）模式

yaml

ls:
  .dir: kebab-case
  .*: kebab-case

  packages/*/src:
    .ts: kebab-case
    .tsx: PascalCase

  packages/*/{src,tests}:
    .dir: kebab-case

ignore:
  - .git
  - node_modules
  - "**/dist"
  - "**/coverage"
  - "**/build"

yaml

ls:
  .dir: kebab-case
  .*: kebab-case

  packages/*/src:
    .ts: kebab-case
    .tsx: PascalCase

  packages/*/{src,tests}:
    .dir: kebab-case

ignore:
  - .git
  - node_modules
  - "**/dist"
  - "**/coverage"
  - "**/build"

GitHub Actions Integration

GitHub Actions集成

Basic workflow configuration:

yaml

undefined

基础工作流配置：

yaml

undefined

.github/workflows/lint.yml

name: Lint on: [push, pull_request]

jobs: ls-lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: ls-lint/action@v2

undefined

name: Lint on: [push, pull_request]

jobs: ls-lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: ls-lint/action@v2

undefined

Action Configuration Options

Action配置选项

yaml

- uses: ls-lint/action@v2
  with:
    config: .ls-lint.yml          # Config file path
    workdir: .                    # Working directory
    error-output-format: text     # text or json
    warn: false                   # Output to stdout, exit 0
    debug: false                  # Enable debug output

yaml

- uses: ls-lint/action@v2
  with:
    config: .ls-lint.yml          # 配置文件路径
    workdir: .                    # 工作目录
    error-output-format: text     # 输出格式：text或json
    warn: false                   # 输出到标准输出，退出码为0
    debug: false                  # 启用调试输出

Troubleshooting

故障排除

Common Issues

常见问题

No files matched: Verify path patterns match actual directory structure.

Rule not applying: Check for more specific rules that might override.

Ignore not working: Ensure ignore patterns use correct glob syntax.

无文件匹配：请检查路径模式是否与实际目录结构匹配。

规则未生效：检查是否存在更具体的规则覆盖了当前规则。

忽略规则不生效：确保忽略模式使用了正确的通配符语法。

Debug Mode

调试模式

Run with verbose output to diagnose issues:

bash

ls-lint --debug

运行时启用详细输出来诊断问题：

bash

ls-lint --debug

External Resources

外部资源

For features not covered in this skill, consult:

GitHub Repository: https://github.com/loeffel-io/ls-lint
Official Documentation: https://ls-lint.org/2.3/getting-started/introduction.html
GitHub Action: https://github.com/ls-lint/action

The official documentation covers additional features like:

Multiple configuration files
Bazel integration
Docker usage
Complete regex syntax

如需了解本Skill未涵盖的功能，请查阅：

GitHub仓库：https://github.com/loeffel-io/ls-lint
官方文档：https://ls-lint.org/2.3/getting-started/introduction.html
GitHub Action：https://github.com/ls-lint/action

官方文档还涵盖了以下额外功能：

多配置文件
Bazel集成
Docker使用
完整正则表达式语法