-
-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathREADME
299 lines (219 loc) · 17.1 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
<div id="description"></div>
# rnm
Bulk Rename Utility written in `C++`. Files and directories can be passed as command line arguments to rename them in bulk according to some naming scheme (*Name String*). If any file or directory path is not passed as command line arguement, it will wait for user to type the path i.e it will take the path from standard input `(>=version 3.0.1)`. It uses `C++` regex (<a href="http://www.cplusplus.com/reference/regex/ECMAScript/">ECMAScript regex</a>) as the default regex to provide search (and replace) functionality, other regex modes are available through (`-re`) option. It provides an undo functionality too to move back an unwanted rename operation. You can also run a simulation instead of actual rename to view the potential outcome as program output on terminal with the `-sim` option.
<div id="features"></div>
#Features:
1. Both directories and files can be renamed.
2. Undo functionality (`rnm -u`).
3. Multiple directories and files can be passed as command line arguments.
4. File name can be modified at runtime by passing a *Name String* as argument.
5. File name can be generated by performing regex replace on old file name with *Replace String* (`-rs`).
6. Selective rename is possible by passing a *Search String* (`-ss`) as argument which will take only the files that matches the search string ( *Search String* is a <a href="https://en.wikipedia.org/wiki/Regular_expression">regex</a> by default). To use a fixed string use the `-ssf` option.
7. Name can be taken from a file too. And these names (taken from a file) can be modified with *Name String* at runtime.
8. Name can be taken from a file according to starting line number (`-l` or `-sl`) and ending line number (`-el`).
9. Null terminated file can be taken as Name String File.
10. Files or directories can be sorted in natural order or general alphabetical order.
<div id="install"></div>
#Install:
###Unix (32 or 64 bit):
1. Give the <span class="quote">install</span> file execution permission (`chmod +x install`) and
2. Run it or just drag and dropt it on terminal and hit <kbd>Enter</kbd> (requires root privilege).
The install script depends on <span class="quote">Bash Shell</span>. If you don't have `bash` installed, then just copy the suitable binary file (`rnm`) from *bin/x32* or *bin/x64* directory to */usr/bin* directory, and copy the <span class="quote">rnm.1</span> file to */usr/share/man/man1* directory.
###Ubuntu:
Aside from the above generalized method, you can also install it in Ubuntu from PPA (`ppa:neurobin/ppa`).
```
sudo add-apt-repository -y ppa:neurobin/ppa
sudo apt-get update
sudo apt-get install rnm
```
<div id="un-install"></div>
#Uninstall:
1. Give the <span class="quote">uninstall</span> file execution permission and
2. Run it or just drag and dropt it on terminal and hit <kbd>Enter</kbd> (requires root privilege).
<div id="usage"></div>
#Usage:
```
rnm directory/file/path -ns new_name [other options]
rnm directory/file/path -rs "/search regex/replace string/gi" [other_options]
rnm directory/file/path -nsf namestring/file/path
```
One of the options of `-ns` or `-nsf` or `-rs` is mandatory. Options are **not** sequential, their position in the argument list have no siginificance. For example, `rnm filepath -ns name` is the same as `rnm -ns name filepath`. Though passing the *Directory/File* path at the end of the arguement list is considered to be safe and wise.
Options are case insensitive, i.e `-ssF` and `-ssf` are the same.
<div id="options"></div>
##Options:
`-h`, `--help` : Show help menu.
`--index`, `--start-index`,
`-i`,`-si` : Starting index.
`--end-index`,
`-ei` : End index i.e index to stop renaming from. It is only for files
inside a directory that is being recursively taken due to a depth
value greater than 0, i.e it works on directory index.
Note that directory index `/id/` will renew in each directory
i.e in each directory rename will be performed from start index
to end index.
`--increment-value`,
`-inc` : Increment value (floating point decimal). The amount, index will be
incremented or decremented in each iteration. Decremented index is
available through name string rule: `/-i/`, `/-id/` etc..
`--line-increment-value`,
`-linc` : The amount line count will be incremented or decremented in each iteration.
This is always a positive integer.
`-ifl` : Index field length. Non occupied field will be
filled with index field fillers (set with `-iff`). iff is set to the character `0` by default.
`--index-field-filler`,
`-iff` : Not occupied field in index will be filled with a character
which is set by this option.
`--index-field-precision`,
`-ifp` : Index is a floating point decimal value. This sets the precision
i.e the number of digits that should be taken after the decimal point.
`--name-string`,
`-ns` : Name string.
`--name-string-file`,
`-nsf` : Name string file. File containing name string (one per line).
`-nsf /hist/` i.e a value passed `/hist/` as Name string file, will
try to take the file from history.
`--name-string-file-null-terminated`,
`-nsfn` : Name String file. This takes a null terminated *Name String* file, i.e
filenames are terminated by null character (`\0`) instead of new line (`\n`).
`--line`, `--start-line`,
`-l`, `-sl` : Start Line number in name string file.
`--line-reverse`, `--start-line-reverse`,
`-lv`, `-slv` : Same as `-l` or `-sl`, except line number will be decremented in each
iteration.
`--end-line`,
`-el` : End line number. Line number to stop renaming from.
`--end-line-reverse`,
`-elv` : Same as `-el`, except line number will be decremented in each iteration.
`--search-string`,
`-ss` : Search string.
String that will be used to search for files with matching names.
This is generally a regex if not pass with `-ssf` option.
`--search-string-fixed`,
`-ssf` : Fixed search string (not treated as regex).
`--replace-string`,
`-rs` : Replace string. A string in the form `/search_string/replace_string/modifier`. See **Replace String** in <a href="rnm/#technical-terms">Terminology</a> for details.
`--regex`,
`-re` : regex mode. Available regex modes are POSIX compliant basic & extended regex,
regex used by grep, awk, egrep and the default regex is ECMAScript regex.
For example, to have a grep like regex, pass the option `-re grep`, to use
POSIX compliant extended regex, pass `-re extended`
`--regex-locale`,
`-rel` : If this is passed as argument, regex will follow Locale. that is regex like
[a-z] will have their meaning according to the system locale.
`--depth`,
`-dp` : Depth of folder. -1(any negative number) means unlimited depth i.e all files and subdirectories
will be included. Other values may be 0 1 2 3 etc...
Default depth is `0`, i.e directory contents will be ignored.
`--file-only`,
`-fo` : File only mode. Only files are renamed (not directory).
Goes to subdirectory/s if depth (`-dp`) is set to `1` or greater.
Default depth is set to 0.
`--directory-only`,
`-do` : Apply rename on directory only. No subdirectories.
`--exclude-directory`,
`-ed` : Apply rename on files only, exclude any and all directory and their
contents. Forces file only mode regardless of depth (-dp) value.
`--count-directory`,
`-cd` : Count directory in reserved index, regardless of other options. Reserves indices for directories even if it is File Only mode.
`--count-file`,
`-cf` : Count file in reserved index, regardless of other options. Reserves indices for files even if it is Directory Only mode.
`--sort`,
`-s` : Sort files in natural order (Human perceivable order). This option can be modified to use other sorting methods. For example: `-s/g` or `--sort/g` will sort the file in general (alphabetical) order. Other options are `-s/n` (Natural sort), `-s/none` (No sort).
`-y` : Confirm Yes to all.
`-u`, `-U`, `--undo` : Undo renaming
`--force`, `-f` : Force rename. Enables renaming some restricted files except `/` and the program itself.
`-v` : Version info.
`-q` : Quiet operation.
`--` : If this option is passed, anything and everything after it will be taken as file path. Put all options before passing this option.
`--show-options`,
`-shop` : This shows an info about the various options passed as arguments
and how they are being treated behind the scene.
`--simulation`,
`-sim` : This runs a simulation of rename instead of actual rename operation,
and prints all kinds of available outputs. `-q` option won't have any
effect if this option is passed.
<div id="technical-terms"></div>
##Technical Terms:
**Reserved Index :** Index will be incremented even if
any file is skipped renaming in order
to reserve the index for that skipped file
**Reverse Index :** Decrementing index.
**Name String :** A string, that is parsed to create names for new files. It can be fixed name which then can be modified for different files at runtime.
Name sting is parsed by the following rules (must be wrapped around with filepath delimiter `/`):
1. `/i/` in name string will be replaced with index.
2. `/ir/` in name string will be replaced with reserved index.
3. `/id/` in name string will be replaced with directory index (index inside a directory).
4. `/idr/` in name string will be replaced with reserved directory index
5. `/-i/` in name string will be replaced with inverse index.
6. `/-ir/` in name string will be replaced with inverse reserved index. In general, `-i` in the above replacement rules (applies to indexes excluding line indexes) will mean inverse index conforming to their meaning.
7. `/dc/` in name string will be replaced with directory count
8. `/l/` in name string will be replaced with line number from *Name String File*.
9. `/la/` in name string will be replaced wiht actual line number from *Name String File*.
10. `/n/` in name string will be replaced with filename without extention. If used with `-nsf` option, the filename will be the name taken from the *Name String File*.
11. `/fn/` in name string will be replaced with full name of the files. If used with `-nsf` option, full name will be the name taken from the *Name String File*.
12. `/rn/` in name string will be replaced with Replaced Name.
13. `/pd/` in name string will be replaced with parent directory name of the current file or directory.
14. `/wd/` in name string will be replaced with the current working directory name.
**Name String File :** A file which contains a list of name string (one per line).
Empty lines will be ignored and line number won't be counted.
Actual line number (which counts the empty lines too) is
available through name string rule : `/la/`.
**Search String :** A string that is used to search for files with matching
filenames against the search string. By default it is
a regex if `-ssF` option is not used.It is generally in the form `/regex/modifier` ,
where <u>regex</u> is the regex to search for and available modifier is <u>i</u> which implies case
insensitive search. If no modifier is used, the regex format can be
reduced to `/regex/` or simply `regex`.
**Index Field Length:** An integer value defining the field length of index.
By default empty field will be filled with 0's. For example, if
the value is `3`, then index will be `001`, `002`, `003`, etc..
Different filler (other than 0) can be provided with the `-iff` option.
**Replaced Name :** The name can be modified at runtime using replace string.
replace string will be parsed to create a new *Name String* rule: `/rn/`
which can be used in *Name String*. If name string is not passed as argument,
the new name of the file will be `/rn/`. *Replaced Name* is always
generated from the old filename.
**Replace String :** *Replace String* is a regex of the form:
`/search_part/replace_part/modifier`
where search_part is the regex to search for and
replace_part is the string to replace with. Name String rules are
avalilable in search_part and replace_part in Replace String.
Regarding replace string, there are four special cases:
1. `&` will be taken as the entire match found by the regex (search_part).
2. `\1`, `\2` etc.. is the back-references, i.e you can access captured groups with these back-references.
3. `\p` is the prefix (i.e., the part of the target sequence that precedes the match)
4. `\s` is the suffix (i.e., the part of the target sequence that follows the match).
to insert a `&` literally, use `\&` and for `\` use `\\`.Two modifiers are avalilable: g and i.
g stands for global and replaces every instances of match found.
i stands case insensitive search (default is case sensitive).*Replace String* is always performed on old file name.
```
Example: '/video/Episode /i//gi' will replace every instances
of 'video' with 'Episode index' i.e you will get new rname as:.
Episode 1..., Episode 2..., etc...
```
**Regex :** Supported regexes are POSIX compliant <a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_03">basic</a> & <a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04">extended</a> regex, grep, egrep and <a href="http://pubs.opengroup.org/onlinepubs/9699919799/utilities/awk.html#tag_20_06_13_04">awk</a> type regexes and the default <a href="http://www.cplusplus.com/reference/regex/ECMAScript/">ECMAScript Regex</a>. You can change the regex mode with `-re` or `--regex` option.
Only invalid characters for a file or directory name is the path delimiter and the null character (`\0`).
<div id="examples"></div>
###Example:
```
rnm file -ns new_file
rnm file -rs "/f/F/" ( will replace f with F in the name, i.e new name will be: File)
rnm folder -ns "New Folder" -do (-do forces Directory only mode)
rnm ./New*/* -ns /i/.ext (globbing is allowed)
rnm ./New*/* -ns /i/.ext -ed (-ed forces file only mode)
rnm "./New Folder" -ns /id//dc/.ext -dp 1 -fo (This will go inside the New Folder directory)
rnm ./New* -ns /id/.ext -ss "regex"
rnm -nsf filepath -ns /n//id/.ext
rnm -nsf filepath
etc...
```
<div id="things-to-care"></div>
#Things to care:
1. All options should always be separated by space. For Example: `-vy` won't mean two option `-v` and `-y`, rather it will mean a single option `-vy`.
2. Any non option argument will be treated as file or directory path. For example in <pre><code>rnm file1 file2 -- -ns fd</code></pre>`file1`, `file2` and `--` will be taken as file paths.
3. Be wary of filename globbing. Command like `rnm ./*` will take all files and directories as arguments and thus the files and directories will be subject to rename operation. If you don't want to rename directories, use file only mode (`-fo`). If you want to go inside directories, use depth (`-dp`) greater than `0` with file only mode.
4. If you run `rnm . -ns something` or `rnm ./ -ns something`, your current directory will be renamed (be careful).
5. This is a dangerous tool like `rm`, so use with care. If you make a mistake and do some unwanted rename, run `rnm -u` to undo (before running any more `rnm` command).
6. Pass all regex like strings within quotes even if they don't contain any white space.
7. To pass a filename that resembles an option, use `./`, i.e `./-ns` to pass a file named `-ns` in the current directory. Or you can use the `--` option make it a non-option argument; in that case make sure to pass all "Option" arguments before `--`, because everything after `--` will be taken as file path/s.
8. Pass file or directory path list at the end of the argument sequence. Use `--` to make all the argumets after it as paths (not options).