README.md
1# brename -- a practical cross-platform command-line tool for safely batch renaming files/directories via regular expression
2
3[](https://golang.org)
4[](https://goreportcard.com/report/github.com/shenwei356/brename)
5[](#download)
6[](https://github.com/shenwei356/brename/releases)
7[](https://github.com/shenwei356/brename/releases)
8
9`brename` is a cross-platform command-line tool for safely batch renaming files/directories via regular expression.
10
11## Table of Contents
12<!-- START doctoc generated TOC please keep comment here to allow auto update -->
13<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
14
15- [Features](#features)
16- [Installation](#installation)
17- [Usage](#usage)
18- [Examples](#examples)
19- [Real-world examples](#real-world-examples)
20- [Contact](#contact)
21- [License](#license)
22- [Starchart](#starchart)
23
24<!-- END doctoc generated TOC please keep comment here to allow auto update -->
25
26## Features
27
28- **Cross-platform**. Supporting Windows, Mac OS X and Linux.
29- **Safe**. By ***checking potential conflicts and errors***.
30- **Supporting Undo**.
31- **Overwrite can be detected and users can choose whether overwrite or leave it**.
32- **File filtering**. Supporting including and excluding files via regular expression.
33 No need to run commands like `find ./ -name "*.html" -exec CMD`.
34- **Renaming submatch with corresponding value via key-value file**.
35- **Renaming via ascending integer**.
36- **Recursively renaming both files and directories**.
37- **Supporting dry run**.
38- **Colorful output**. Screenshots:
39 - Linux
40
41 
42 - Windows
43
44 
45
46## Installation
47
48`brename` is implemented in [Go](https://golang.org/) programming language,
49 executable binary files **for most popular operating systems** are freely available
50 in [release](https://github.com/shenwei356/brename/releases) page.
51
52#### Method 1: Download binaries
53
54[brename v2.11.1](https://github.com/shenwei356/brename/releases/tag/v2.11.1)
55[](https://github.com/shenwei356/brename/releases/tag/v2.11.1)
56
57***Tip: run `brename -V` to check update !!!***
58
59OS |Arch |File, 中国镜像 |Download Count
60:------|:---------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
61Linux |32-bit |[brename_linux_386.tar.gz](https://github.com/shenwei356/brename/releases/download/v2.11.1/brename_linux_386.tar.gz),<br/> [中国镜像](http://app.shenwei.me/data/brename/brename_linux_386.tar.gz) |[](https://github.com/shenwei356/brename/releases/download/v2.11.1/brename_linux_386.tar.gz)
62Linux |**64-bit**|[**brename_linux_amd64.tar.gz**](https://github.com/shenwei356/brename/releases/download/v2.11.1/brename_linux_amd64.tar.gz),<br/> [中国镜像](http://app.shenwei.me/data/brename/brename_linux_amd64.tar.gz) |[](https://github.com/shenwei356/brename/releases/download/v2.11.1/brename_linux_amd64.tar.gz)
63Linux |arm64 |[**brename_linux_arm64.tar.gz**](https://github.com/shenwei356/brename/releases/download/v2.11.1/brename_linux_arm64.tar.gz),<br/> [中国镜像](http://app.shenwei.me/data/brename/brename_linux_arm64.tar.gz) |[](https://github.com/shenwei356/brename/releases/download/v2.11.1/brename_linux_arm64.tar.gz)
64OS X |**64-bit**|[**brename_darwin_amd64.tar.gz**](https://github.com/shenwei356/brename/releases/download/v2.11.1/brename_darwin_amd64.tar.gz),<br/> [中国镜像](http://app.shenwei.me/data/brename/brename_darwin_amd64.tar.gz) |[](https://github.com/shenwei356/brename/releases/download/v2.11.1/brename_darwin_amd64.tar.gz)
65OS X |arm64 |[**brename_darwin_arm64.tar.gz**](https://github.com/shenwei356/brename/releases/download/v2.11.1/brename_darwin_arm64.tar.gz),<br/> [中国镜像](http://app.shenwei.me/data/brename/brename_darwin_arm64.tar.gz) |[](https://github.com/shenwei356/brename/releases/download/v2.11.1/brename_darwin_arm64.tar.gz)
66Windows|32-bit |[brename_windows_386.exe.tar.gz](https://github.com/shenwei356/brename/releases/download/v2.11.1/brename_windows_386.exe.tar.gz),<br/> [中国镜像](http://app.shenwei.me/data/brename/brename_windows_386.exe.tar.gz) |[](https://github.com/shenwei356/brename/releases/download/v2.11.1/brename_windows_386.exe.tar.gz)
67Windows|**64-bit**|[**brename_windows_amd64.exe.tar.gz**](https://github.com/shenwei356/brename/releases/download/v2.11.1/brename_windows_amd64.exe.tar.gz),<br/> [中国镜像](http://app.shenwei.me/data/brename/brename_windows_amd64.exe.tar.gz)|[](https://github.com/shenwei356/brename/releases/download/v2.11.1/brename_windows_amd64.exe.tar.gz)
68
69
70Just [download](https://github.com/shenwei356/brename/releases) compressed
71executable file of your operating system,
72and decompress it with `tar -zxvf *.tar.gz` command or other tools.
73And then:
74
751. **For Linux-like systems**
76 1. If you have root privilege simply copy it to `/usr/local/bin`:
77
78 sudo cp brename /usr/local/bin/
79
80 1. Or copy to anywhere in the environment variable `PATH`:
81
82 mkdir -p $HOME/bin/; cp brename $HOME/bin/
83
841. **For windows**, just copy `brename.exe` to `C:\WINDOWS\system32`.
85
86#### Method 2: For Go developer
87
88 go get -u github.com/shenwei356/brename/
89
90#### Method 3: For ArchLinux AUR users
91
92 yaourt -S brename
93
94#### Method 4: For Scoop users
95
96 scoop install brename
97
98## Usage
99
100```
101
102brename -- a practical cross-platform command-line tool for safely batch renaming files/directories via regular expression
103
104Version: 2.11.1
105
106Author: Wei Shen <shenwei356@gmail.com>
107
108Homepage: https://github.com/shenwei356/brename
109
110Attention:
111 1. Paths starting with "." are ignored.
112 2. Flag -f/--include-filters and -F/--exclude-filters support multiple values,
113 e.g., -f ".html" -f ".htm".
114 But ATTENTION: comma in filter is treated as separator of multiple filters.
115
116Special replacement symbols:
117
118 {nr} Ascending integer
119 {kv} Corresponding value of the key (captured variable $n) by key-value file,
120 n can be specified by flag -I/--key-capt-idx (default: 1)
121
122Usage:
123 brename [flags] [path ...]
124
125Examples:
126 1. dry run and showing potential dangerous operations
127 brename -p "abc" -d
128 2. dry run and only show operations that will cause error
129 brename -p "abc" -d -v 2
130 3. only renaming specific paths via include filters
131 brename -p ":" -r "-" -f ".htm$" -f ".html$"
132 4. renaming all .jpeg files to .jpg in all subdirectories
133 brename -p "\.jpeg" -r ".jpg" -R dir
134 5. using capture variables, e.g., $1, $2 ...
135 brename -p "(a)" -r "\$1\$1"
136 or brename -p "(a)" -r '$1$1' in Linux/Mac OS X
137 6. renaming directory too
138 brename -p ":" -r "-" -R -D pdf-dirs
139 7. using key-value file
140 brename -p "(.+)" -r "{kv}" -k kv.tsv
141 8. do not touch file extension
142 brename -p ".+" -r "{nr}" -f .mkv -f .mp4 -e
143 9. only list paths that match pattern (-l)
144 brename -i -f '.docx?$' -p . -R -l
145 10. undo the LAST successful operation
146 brename -u
147
148 More examples: https://github.com/shenwei356/brename
149
150Flags:
151 -d, --dry-run print rename operations but do not run
152 -F, --exclude-filters strings exclude file filter(s) (regular expression, NOT wildcard). multiple values supported, e.g., -F ".html" -F ".htm", but ATTENTION: comma in filter is treated as separator of multiple filters
153 -U, --force-undo continue undo even when some operations failed
154 -h, --help help for brename
155 -i, --ignore-case ignore case of -p/--pattern, -f/--include-filters and -F/--exclude-filters
156 -e, --ignore-ext ignore file extension. i.e., replacement does not change file extension
157 -f, --include-filters strings include file filter(s) (regular expression, NOT wildcard). multiple values supported, e.g., -f ".html" -f ".htm", but ATTENTION: comma in filter is treated as separator of multiple filters (default [.])
158 -D, --including-dir rename directories
159 -K, --keep-key keep the key as value when no value found for the key
160 -I, --key-capt-idx int capture variable index of key (1-based) (default 1)
161 -m, --key-miss-repl string replacement for key with no corresponding value
162 -k, --kv-file string tab-delimited key-value file for replacing key with value when using "{kv}" in -r (--replacement)
163 -l, --list only list paths that match pattern
164 -a, --list-abs list absolute path, using along with -l/--list
165 -s, --list-sep string separator for list of found paths (default "\n")
166 --max-depth int maximum depth for recursive search (0 for no limit)
167 -N, --nature-sort list paths in nature sort, using along with -l/--list
168 --nr-width int minimum width for {nr} in flag -r/--replacement. e.g., formating "1" to "001" by --nr-width 3 (default 1)
169 --only-dir only rename directories
170 -o, --overwrite-mode int overwrite mode (0 for reporting error, 1 for overwrite, 2 for not renaming) (default 0)
171 -p, --pattern string search pattern (regular expression)
172 -q, --quiet be quiet, do not show information and warning
173 -R, --recursive rename recursively
174 -r, --replacement string replacement. capture variables supported. e.g. $1 represents the first submatch. ATTENTION: for *nix OS, use SINGLE quote NOT double quotes or use the \ escape character. Ascending integer is also supported by "{nr}"
175 -n, --start-num int starting number when using {nr} in replacement (default 1)
176 -u, --undo undo the LAST successful operation
177 -v, --verbose int verbose level (0 for all, 1 for warning and error, 2 for only error) (default 0)
178 -V, --version print version information and check for update
179
180```
181
182
183## Examples
184
185Take a directory for example (run `generate-example-folder.sh` to generate)
186
187 $ sh generate-example-folder.sh
188 example
189 ├── abc
190 │ ├── A.JPEG
191 │ ├── B.HTM
192 │ └── B.JPEG
193 ├── a.html
194 ├── a.jpeg
195 └── b.jpeg
196
197 # examples below were executed in directory: example
198 cd example/
199
200
2011. Recursively renaming all `.jpeg` files to `.jpg` in all subdirectories (`-R/--recursive`).
202 A dry run is firstly performed for safety checking (`-d/--dry-run`).
203
204 $ brename -p "\.jpeg" -r ".jpg" -R -d
205 [INFO] main options:
206 [INFO] ignore case: false
207 [INFO] search pattern: \.jpeg
208 [INFO] include filters: .
209 [INFO] search paths: ./
210 [INFO]
211 [INFO] checking: [ ok ] 'a.jpeg' -> 'a.jpg'
212 [INFO] checking: [ ok ] 'b.jpeg' -> 'b.jpg'
213 [INFO] 2 path(s) to be renamed
214
215
216 $ brename -p "\.jpeg" -r ".jpg" -R
217 [INFO] main options:
218 [INFO] ignore case: false
219 [INFO] search pattern: \.jpeg
220 [INFO] include filters: .
221 [INFO] search paths: ./
222 [INFO]
223 [INFO] checking: [ ok ] 'a.jpeg' -> 'a.jpg'
224 [INFO] checking: [ ok ] 'b.jpeg' -> 'b.jpg'
225 [INFO] 2 path(s) to be renamed
226 [INFO] renamed: 'a.jpeg' -> 'a.jpg'
227 [INFO] renamed: 'b.jpeg' -> 'b.jpg'
228 [INFO] 2 path(s) renamed
229
230 $ tree
231 .
232 ├── abc
233 │ ├── A.JPEG
234 │ ├── B.HTM
235 │ └── B.JPEG
236 ├── a.html
237 ├── a.jpg
238 └── b.jpg
239
240
2411. **Undo** the LAST successful operation, yes it's COOL! (`-u/--undo`, `-U/--force-undo`)
242
243 $ brename -u
244 [INFO] rename back: 'b.jpg' -> 'b.jpeg'
245 [INFO] rename back: 'a.jpg' -> 'a.jpeg'
246 [INFO] 2 path(s) renamed
247
2481. Dry run and only showing operations that will cause error (`-v/--verbose`)
249
250 # default value of -v is 0
251 $ brename -p a -r b -R -D -d
252 [INFO] checking: [ ok ] 'a.html' -> 'b.html'
253 [ERRO] checking: [ new path existed ] 'a.jpg' -> 'b.jpg'
254 [INFO] checking: [ ok ] 'abc' -> 'bbc'
255 [ERRO] 1 potential error(s) detected, please check
256
257 $ brename -p a -r b -R -D -d -v 2
258 [ERRO] checking: [ new path existed ] 'a.jpg' -> 'b.jpg'
259 [ERRO] 1 potential error(s) detected, please check
260
2611. Ignoring cases (`-i/--ignore-case`)
262
263 $ brename -p "\.jpeg" -r ".jpg" -R -i
264 [INFO] checking: [ ok ] 'abc/A.JPEG' -> 'abc/A.jpg'
265 [INFO] checking: [ ok ] 'abc/B.JPEG' -> 'abc/B.jpg'
266 [INFO] 2 path(s) to be renamed
267 [INFO] renamed: 'abc/A.JPEG' -> 'abc/A.jpg'
268 [INFO] renamed: 'abc/B.JPEG' -> 'abc/B.jpg'
269 [INFO] 2 path(s) renamed
270
271 $ tree
272 .
273 ├── abc
274 │ ├── A.jpg
275 │ ├── B.HTM
276 │ └── B.jpg
277 ├── a.html
278 ├── a.jpg
279 └── b.jpg
280
2811. Using capture variables, e.g., $1, $2 ...
282
283 # or brename -p "(a)" -r '$1$1' in Linux/Mac OS X
284 $ brename -p "(a)" -r "\$1\$1" -i
285 [INFO] checking: [ ok ] 'a.html' -> 'aa.html'
286 [INFO] checking: [ ok ] 'a.jpg' -> 'aa.jpg'
287 [INFO] 2 path(s) to be renamed
288 [INFO] renamed: 'a.html' -> 'aa.html'
289 [INFO] renamed: 'a.jpg' -> 'aa.jpg'
290 [INFO] 2 path(s) renamed
291
292 $ tree
293 .
294 ├── aa.html
295 ├── aa.jpg
296 ├── abc
297 │ ├── A.jpg
298 │ ├── B.HTM
299 │ └── B.jpg
300 └── b.jpg
301
3021. Renaming directory too (`-D/--including-dir`), even renaming directory only (`-D --only-dir`)
303
304 $ brename -p "a" -r "A" -R -D
305 [INFO] checking: [ ok ] 'aa.html' -> 'AA.html'
306 [INFO] checking: [ ok ] 'aa.jpg' -> 'AA.jpg'
307 [INFO] checking: [ ok ] 'abc' -> 'Abc'
308 [INFO] 3 path(s) to be renamed
309 [INFO] renamed: 'aa.html' -> 'AA.html'
310 [INFO] renamed: 'aa.jpg' -> 'AA.jpg'
311 [INFO] renamed: 'abc' -> 'Abc'
312 [INFO] 3 path(s) renamed
313
314 $ tree
315 .
316 ├── AA.html
317 ├── AA.jpg
318 ├── Abc
319 │ ├── A.jpg
320 │ ├── B.HTM
321 │ └── B.jpg
322 └── b.jpg
323
324
3251. **Only renaming specific files via include filters (regular expression) (`-f/--include-filters`)**
326
327 $ brename -p '(.)' -r '$1 ' -d
328 [INFO] main options:
329 [INFO] ignore case: false
330 [INFO] search pattern: (.)
331 [INFO] include filters: .
332 [INFO] search paths: ./
333 [INFO]
334 [INFO] checking: [ ok ] 'AA.html' -> 'A A . h t m l '
335 [INFO] checking: [ ok ] 'AA.jpg' -> 'A A . j p g '
336 [INFO] checking: [ ok ] 'b.jpg' -> 'b . j p g '
337 [INFO] 3 path(s) to be renamed
338
339
340 $ brename -p '(.)' -r '$1 ' -d -f '\.jpg$'
341 [INFO] main options:
342 [INFO] ignore case: false
343 [INFO] search pattern: (.)
344 [INFO] include filters: \.jpg$
345 [INFO] search paths: ./
346 [INFO]
347 [INFO] checking: [ ok ] 'AA.jpg' -> 'A A . j p g '
348 [INFO] checking: [ ok ] 'b.jpg' -> 'b . j p g '
349 [INFO] 2 path(s) to be renamed
350
351
352 ***Attention: value of `-f/--include-filters` and `-F/--exclude-filters` should be regular expression, NOT wildcard!***
353
354 $ brename -p '(.)' -r '$1 ' -d -f *.jpg
355 [WARN] Seems you are using wildcard for -f/--include-filters? Make sure using regular expression: AA.jpg
356 [INFO] main options:
357 [INFO] ignore case: false
358 [INFO] search pattern: (.)
359 [INFO] include filters: AA.jpg
360 [INFO] search paths: b.jpg
361 [INFO]
362 [INFO] 0 path(s) to be renamed
363
364 $ brename -p '(.)' -r '$1 ' -d -f '*.jpg'
365 [WARN] Are you using wildcard for -f/--include-filters? It should be regular expression: *.jpg
366 [ERRO] illegal regular expression for include filter: *.jpg
367
368 $ brename -p '(.)' -r '$1 ' -d -f A*
369 [WARN] Seems you are using wildcard for -f/--include-filters? Make sure using regular expression: AA.html
370 [INFO] main options:
371 [INFO] ignore case: false
372 [INFO] search pattern: (.)
373 [INFO] include filters: AA.html
374 [INFO] search paths: AA.jpg, Abc
375 [INFO]
376 [INFO] 0 path(s) to be renamed
377
3781. Excluding files via exclude filters (regular expression) (`-F/--exclude-filters`)
379
380 $ brename -p '(.)' -r '$1 ' -d
381 [INFO] checking: [ ok ] 'AA.jpg' -> 'A A . j p g '
382 [INFO] checking: [ ok ] 'b.jpg' -> 'b . j p g '
383 [INFO] checking: [ ok ] 'hello AA.html' -> 'h e l l o A A . h t m l '
384 [INFO] 3 path(s) to be renamed
385
386
387 $ brename -p '(.)' -r '$1 ' -d -F '\.html$'
388 [INFO] checking: [ ok ] 'AA.jpg' -> 'A A . j p g '
389 [INFO] checking: [ ok ] 'b.jpg' -> 'b . j p g '
390 [INFO] 2 path(s) to be renamed
391
3921. Do not touch file extension (`-e/--ignore-ext`)
393
394 $ brename -p '(.)' -r '$1 ' -d
395 [INFO] checking: [ ok ] 'AA.jpg' -> 'A A . j p g '
396 [INFO] checking: [ ok ] 'b.jpg' -> 'b . j p g '
397 [INFO] checking: [ ok ] 'hello AA.html' -> 'h e l l o A A . h t m l '
398 [INFO] 3 path(s) to be renamed
399
400 $ brename -p '(.)' -r '$1 ' -d -e
401 [INFO] checking: [ ok ] 'AA.jpg' -> 'A A .jpg'
402 [INFO] checking: [ ok ] 'b.jpg' -> 'b .jpg'
403 [INFO] checking: [ ok ] 'hello AA.html' -> 'h e l l o A A .html'
404 [INFO] 3 path(s) to be renamed
405
4061. Renaming with number (-r `{nr}`)
407
408 $ brename -d -p '(.+)\.' -r 'pic-{nr}.' -f .jpg -d
409 [INFO] checking: [ ok ] 'AA.jpg' -> 'pic-1.jpg'
410 [INFO] checking: [ ok ] 'b.jpg' -> 'pic-2.jpg'
411 [INFO] 2 path(s) to be renamed
412
413 $ brename -d -p '(.+)\.' -r 'pic-{nr}.' -f .jpg -d --nr-width 3 --start-num 11
414 [INFO] checking: [ ok ] 'AA.jpg' -> 'pic-011.jpg'
415 [INFO] checking: [ ok ] 'b.jpg' -> 'pic-012.jpg'
416 [INFO] 2 path(s) to be renamed
417
4181. Replace submatch with corresponding value via tab delimited key-value file (`-k/--kv-file`)
419
420 $ more kv.tsv
421 a 一
422 b 二
423 c 三
424
425 $ brename -p '^(\w)' -r '{kv}' -k kv.tsv -K -i -d
426 [INFO] read key-value file: kv.tsv
427 [INFO] 3 pairs of key-value loaded
428 [INFO] checking: [ ok ] 'AA.jpg' -> '一A.jpg'
429 [INFO] checking: [ ok ] 'b.jpg' -> '二.jpg'
430 [WARN] checking: [ unchanged ] 'hello b.html' -> 'hello b.html'
431 [WARN] checking: [ unchanged ] 'kv.tsv' -> 'kv.tsv'
432
4331. Auto mkdir
434
435 $ brename -f .txt -p '-' -r '/'
436 [INFO] checking: [ ok ] 'a-b-c.txt' -> 'a/b/c.txt'
437 [INFO] 1 path(s) to be renamed
438 [INFO] renamed: 'a-b-c.txt' -> 'a/b/c.txt'
439 [INFO] 1 path(s) renamed
440
441 $ tree a
442 a
443 └── b
444 └── c.txt
445
4461. Only listing paths that match pattern (`-l` and `-a`)
447
448 $ brename -p '.gz$' -R -l
449 binaries/brename_darwin_386.tar.gz
450 binaries/brename_darwin_amd64.tar.gz
451 binaries/brename_linux_386.tar.gz
452 binaries/brename_linux_amd64.tar.gz
453 binaries/brename_windows_386.exe.tar.gz
454 binaries/brename_windows_amd64.exe.tar.gz
455
456 $ brename -p '.gz$' -R -l -a
457 /home/shenwei/project/src/github.com/shenwei356/brename/binaries/brename_darwin_386.tar.gz
458 /home/shenwei/project/src/github.com/shenwei356/brename/binaries/brename_darwin_amd64.tar.gz
459 /home/shenwei/project/src/github.com/shenwei356/brename/binaries/brename_linux_386.tar.gz
460 /home/shenwei/project/src/github.com/shenwei356/brename/binaries/brename_linux_amd64.tar.gz
461 /home/shenwei/project/src/github.com/shenwei356/brename/binaries/brename_windows_386.exe.tar.gz
462 /home/shenwei/project/src/github.com/shenwei356/brename/binaries/brename_windows_amd64.exe.tar.gz
463
4641. Overwrite mode (`-o/--overwrite-mode`)
465
466 $ ls *.tar.gz
467 brename_darwin_386.tar.gz brename_linux_386.tar.gz brename_windows_386.exe.tar.gz
468 brename_darwin_amd64.tar.gz brename_linux_amd64.tar.gz brename_windows_amd64.exe.tar.gz
469
470 1. default mode: reporting error
471
472 $ brename -p 386 -r amd64 -d
473 [ERRO] checking: [ new path existed ] 'brename_darwin_386.tar.gz' -> 'brename_darwin_amd64.tar.gz'
474 [ERRO] checking: [ new path existed ] 'brename_linux_386.tar.gz' -> 'brename_linux_amd64.tar.gz'
475 [ERRO] checking: [ new path existed ] 'brename_windows_386.exe.tar.gz' -> 'brename_windows_amd64.exe.tar.gz'
476 [ERRO] 3 potential error(s) detected, please check
477
478 1. allowing overwrite
479
480 $ brename -p 386 -r amd64 -d -o 1
481 [WARN] checking: [ new path existed ] 'brename_darwin_386.tar.gz' -> 'brename_darwin_amd64.tar.gz' (will be overwrited)
482 [WARN] checking: [ new path existed ] 'brename_linux_386.tar.gz' -> 'brename_linux_amd64.tar.gz' (will be overwrited)
483 [WARN] checking: [ new path existed ] 'brename_windows_386.exe.tar.gz' -> 'brename_windows_amd64.exe.tar.gz' (will be overwrited)
484 [INFO] 3 path(s) to be renamed
485
486 1. leave it
487
488 $ brename -p 386 -r amd64 -d -o 2
489 [WARN] checking: [ new path existed ] 'brename_darwin_386.tar.gz' -> 'brename_darwin_amd64.tar.gz' (will NOT be overwrited)
490 [WARN] checking: [ new path existed ] 'brename_linux_386.tar.gz' -> 'brename_linux_amd64.tar.gz' (will NOT be overwrited)
491 [WARN] checking: [ new path existed ] 'brename_windows_386.exe.tar.gz' -> 'brename_windows_amd64.exe.tar.gz' (will NOT be overwrited)
492 [INFO] 0 path(s) to be renamed
493
494 1. this flag also works for another case, where two or more files are renamed to same new path
495
496 $ brename -f 386 -p 'darwin|linux' -r unix-like -d
497 [INFO] checking: [ ok ] 'brename_darwin_386.tar.gz' -> 'brename_unix-like_386.tar.gz'
498 [ERRO] checking: [ overwriting newly renamed path ] 'brename_linux_386.tar.gz' -> 'brename_unix-like_386.tar.gz'
499 [ERRO] 1 potential error(s) detected, please check
500
501 $ brename -f 386 -p 'darwin|linux' -r unix-like -d -o 1
502 [INFO] checking: [ ok ] 'brename_darwin_386.tar.gz' -> 'brename_unix-like_386.tar.gz'
503 [WARN] checking: [ overwriting newly renamed path ] 'brename_linux_386.tar.gz' -> 'brename_unix-like_386.tar.gz' (will be overwrited)
504 [INFO] 2 path(s) to be renamed
505
506 $ brename -f 386 -p 'darwin|linux' -r unix-like -d -o 2
507 [INFO] checking: [ ok ] 'brename_darwin_386.tar.gz' -> 'brename_unix-like_386.tar.gz'
508 [WARN] checking: [ overwriting newly renamed path ] 'brename_linux_386.tar.gz' -> 'brename_unix-like_386.tar.gz' (will NOT be overwrited)
509 [INFO] 1 path(s) to be renamed
510
511## Real-world examples
512
5131. Replace matches with corresponding pairing values
514
515 1. Original files
516
517 $ tree
518 .
519 ├── barcodes.tsv
520 ├── tag_ATGCGTA.fasta
521 ├── tag_CCCCCCC.fasta
522 ├── tag_CGACGTC.fasta
523 ├── tag_TCATAGC.fasta
524 └── tag_TCTATAG.fasta
525
526 1. Tab-delimited key-value file. Notice that `CCCCCCC` is not in it.
527
528 $ cat barcodes.tsv
529 CGACGTC S1
530 ATGCGTA S2
531 TCTATAG S4
532 TCATAGC S3
533
534 1. Renaming tag as sample name, marking `unknown` for non-existing tag.
535
536 $ brename -e -p 'tag_(\w+)' -r '{kv}' -k barcodes.tsv -m unknown -d
537 [INFO] read key-value file: barcodes.tsv
538 [INFO] 4 pairs of key-value loaded
539 [INFO] checking: [ ok ] 'tag_ATGCGTA.fasta' -> 'S2.fasta'
540 [INFO] checking: [ ok ] 'tag_CCCCCCC.fasta' -> 'unknown.fasta'
541 [INFO] checking: [ ok ] 'tag_CGACGTC.fasta' -> 'S1.fasta'
542 [INFO] checking: [ ok ] 'tag_TCATAGC.fasta' -> 'S3.fasta'
543 [INFO] checking: [ ok ] 'tag_TCTATAG.fasta' -> 'S4.fasta'
544 [INFO] 5 path(s) to be renamed
545
5461. Renaming PDF files for compatibility (moving from `EXT4` to `NTFS` file system):
547
548 1. Original files
549
550 $ tree -Q
551 .
552 ├── "0000 Test.pdf"
553 ├── "2016 SeqKit _ A Cross-Platform and Ultrafast Toolkit for FASTA\342\201\204Q File Manipulation .pdf"
554 ├── "metagenomics"
555 │ ├── "2017 16S rRNA gene sequencing and healthy reference ranges for 28 clinically relevant microbial taxa from the human gut microbiome .pdf"
556 │ ├── "2017 De novo assembly of viral quasispecies using overlap graphs .pdf"
557 │ └── "2017 Tracking microbial colonization in fecal microbiota transplantation experiments via genome-resolved metagenomics .pdf"
558 ├── "test2222222222222222222211111111122222222222222222233333333.pdf"
559 └── "test.pdf"
560
561 1. Removing "\n", "'", "?".
562
563 $ brename -p "[\n'\?]" -r " " -R
564
565 1. Replacing ":" with "_"
566
567 $ brename -p ":" -r " _" -R
568
569 1. Shortening file names (prefering spliting with space)
570
571 $ brename -R -f .pdf -i -p "^(.{30,50})[ \.].*.pdf" -r "\$1.pdf" -d
572
573 1. Result
574
575 $ tree -Q
576 .
577 ├── "0000 Test.pdf"
578 ├── "2016 SeqKit _ A Cross-Platform and Ultrafast.pdf"
579 ├── "metagenomics"
580 │ ├── "2017 16S rRNA gene sequencing and healthy.pdf"
581 │ ├── "2017 De novo assembly of viral quasispecies using.pdf"
582 │ └── "2017 Tracking microbial colonization in fecal.pdf"
583 ├── "test2222222222222222222211111111122222222222222222233333333.pdf"
584 └── "test.pdf"
585
586## Contact
587
588[Create an issue](https://github.com/shenwei356/brename/issues) to report bugs,
589propose new functions or ask for help.
590
591## License
592
593[MIT License](https://github.com/shenwei356/brename/blob/master/LICENSE)
594
595## Starchart
596
597<img src="https://starchart.cc/shenwei356/brename.svg" alt="Stargazers over time" style="max-width: 100%">
598
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
