You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: AGENT.md
+4-2Lines changed: 4 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,8 +4,10 @@
4
4
- Name GitHub pull requests using the **Conventional Commits** specification. Example: `feat(parser): support new syntax` or `fix(ci): correct clippy invocation`.
5
5
6
6
## Validation Steps
7
-
- Before submitting a PR, run each command from `./run-all.sh` manually. It may
8
-
include:
7
+
- If a PR only changes Markdown documentation (excluding Rust doc comments),
8
+
skip formatting, build and test steps.
9
+
- If Rust source files or `Cargo.toml` were modified, run each command from
-`keepsorted --check <path>` verifies sorting without modifying files.
26
-
-`keepsorted --diff <path>` shows a diff of required changes.
27
-
-`keepsorted --fix <path>` updates files in place.
28
-
- By default `keepsorted` processes a single file. Use `--recursive` (`-r`) to walk a directory and format every supported file. For complex include/exclude rules, combine `keepsorted` with shell tools like `git ls-files`. See [Architecture](docs/architecture.md) for details.
29
-
30
-
Run `keepsorted --check` in CI after filtering tracked files with
31
-
`git ls-files` to prevent unsorted changes.
23
+
## Overview
32
24
33
-
### Pre-commit hook
25
+
`keepsorted` sorts lists of lines while keeping nearby comments with the lines
26
+
that follow them. Add a comment like **`Keep sorted`** and the tool will reorder
27
+
the next block. Some file types are sorted automatically.
34
28
35
-
keepsorted requires explicit paths unless you enable `--recursive`. To scan all tracked files except the test directories, save this script as `.git/hooks/pre-commit`:
29
+
## Usage
36
30
37
31
```shell
38
-
#!/bin/sh
39
-
git ls-files -z \
40
-
| grep -vzE '^tests/|^e2e-tests/|^README.md$' \
41
-
| xargs -0 -n1 keepsorted --check || {
42
-
echo'Run keepsorted --fix'>&2
43
-
exit 1
44
-
}
32
+
keepsorted --check <path># verify without changes
33
+
keepsorted --diff <path># preview changes as a diff
34
+
keepsorted --fix <path># rewrite files in place (default)
45
35
```
46
36
47
-
`keepsorted` is a command-line tool that helps you sort blocks of lines in your code files.
48
-
The tool is inspired by the Bazel build tool `buildifier`, which sorts items marked with `# Keep sorted` comments. `keepsorted` brings this functionality to any text file.
37
+
Use `--recursive` (`-r`) to process directories. Combine with `git ls-files` in
38
+
CI to check only tracked files.
49
39
50
-
It works by sorting lines within a block that starts with the activation comment `# Keep sorted`.
51
-
In some files, like `Cargo.toml`, it sorts automatically without needing an activation comment.
40
+
### Keywords
52
41
53
-
The tool can also recognize comments attached to non-comment lines, like this:
42
+
-`Keep sorted` or `keepsorted: keep sorted` – sort the next block.
43
+
-`keepsorted: ignore file` – skip the whole file.
44
+
-`keepsorted: ignore block` – skip a single block.
54
45
55
-
```py
56
-
# Before:
57
-
dependencies = [
58
-
# Keep sorted.
59
-
'ddd',
60
-
'ccc',
61
-
#TODO: remove this dependency.
62
-
'bbb',
63
-
'aaa',
64
-
]
46
+
Markers work with `#`, `//`, or `--` comments. Generic files and Bazel require
47
+
one of these comments. `Cargo.toml`, `.gitignore`, and `CODEOWNERS` are sorted
48
+
automatically when the matching feature flag is enabled.
65
49
66
-
# After:
67
-
dependencies = [
68
-
# Keep sorted.
69
-
'aaa',
70
-
#TODO: remove this dependency.
71
-
'bbb',
72
-
'ccc',
73
-
'ddd',
74
-
]
50
+
### Examples
51
+
52
+
#### Generic text (Python)
53
+
54
+
```py
55
+
# Keep sorted
56
+
# comment B
57
+
b
58
+
# comment A
59
+
a
75
60
```
76
61
77
-
You can see more examples in the `./e2e-tests/files/` directory.
62
+
becomes
78
63
79
-
## Keywords
64
+
```py
65
+
# Keep sorted
66
+
# comment A
67
+
a
68
+
# comment B
69
+
b
70
+
```
80
71
81
-
Comments can begin with `#`, `//`, or `--`. The following examples use `#`.
72
+
#### Generic text (C++)
73
+
74
+
```cpp
75
+
// Keep sorted
76
+
// comment two
77
+
second
78
+
// comment one
79
+
first
80
+
```
82
81
83
-
-`# Keep sorted` or `# keepsorted: keep sorted` sorts the next block of lines
84
-
-`# keepsorted: ignore file` anywhere in the file skips sorting
85
-
-`# keepsorted: ignore block` within a block skips sorting that block
82
+
becomes
86
83
87
-
## Supported Files
84
+
```cpp
85
+
// Keep sorted
86
+
// comment one
87
+
first
88
+
// comment two
89
+
second
90
+
```
88
91
89
-
### Generic Text Files
92
+
####Generic text (SQL/Lua)
90
93
91
-
For generic text files, the tool sorts blocks that start with `# Keep sorted` and end with a newline.
94
+
```sql
95
+
-- Keep sorted
96
+
-- c comment
97
+
c
98
+
-- a comment
99
+
a
100
+
```
92
101
93
-
```txt
94
-
# Names
95
-
# Keep sorted
96
-
Alice
97
-
Bob
98
-
Conrad
102
+
becomes
99
103
100
-
# Colors
101
-
# Keep sorted
102
-
Blue
103
-
Green
104
-
Red
104
+
```sql
105
+
-- Keep sorted
106
+
-- a comment
107
+
a
108
+
-- c comment
109
+
c
105
110
```
106
111
107
-
### Bazel
112
+
#### Bazel
113
+
114
+
```bazel
115
+
srcs = [
116
+
# Keep sorted
117
+
"b",
118
+
# note for a
119
+
"a",
120
+
]
121
+
```
108
122
109
-
In Bazel files, keepsorted sorts lines within `[...]` blocks that start with `# Keep sorted`.
123
+
becomes
110
124
111
125
```bazel
112
-
DEPENDENCIES= [
126
+
srcs= [
113
127
# Keep sorted
128
+
# note for a
114
129
"a",
115
130
"b",
116
131
]
117
132
```
118
133
119
-
### Cargo.toml
120
-
121
-
In `Cargo.toml` files, the tool sorts lines within blocks that start with `[dependencies]`, `[dev-dependencies]`, etc., and end with an empty line.
134
+
#### Cargo.toml
122
135
123
136
```toml
124
137
[dependencies]
125
-
a = "0.1.0"
126
-
b = { workspace = true }
138
+
b = "2"
139
+
a = "1"
127
140
128
141
# keepsorted: ignore block
129
142
[dev-dependencies]
130
-
y = { workspace = true }
131
-
x = "0.3.0"
143
+
z = "1"
144
+
y = "2"
132
145
```
133
146
134
-
### .gitignore & CODEOWNERS
147
+
becomes
135
148
136
-
*NOTE: These features are experimental and require feature flags.*
In `.gitignore` and `CODEOWNERS` files, the tool sorts blocks separated by empty lines while keeping comments in place, except for the opening block comment.
160
+
#### .gitignore
143
161
144
-
**(!) IMPORTANT**: the order of patterns can be important because it gets executed from top to bottom from more generic to more specific rules, therefore use this feature with extra care.
162
+
```gitignore
163
+
# Build
164
+
/b
165
+
/a
166
+
```
145
167
146
-
```.gitignore
147
-
# Various build artifacts
148
-
**/build
149
-
**/build-out
150
-
**/build-tmp
151
-
artifacts
168
+
becomes
152
169
153
-
# Bazel outdir dirs
154
-
# keepsorted: ignore block
155
-
bazel-c.pb
156
-
user.bazelrc
157
-
bazel-b.txt
158
-
/bazel-*
159
-
bazel-a.txt
170
+
```gitignore
171
+
# Build
172
+
/a
173
+
/b
160
174
```
161
175
162
-
###Rust Derive
176
+
#### CODEOWNERS
163
177
164
-
*NOTE: These features are experimental and require feature flags.*
0 commit comments