-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.man
579 lines (544 loc) · 16.7 KB
/
README.man
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
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
.\" Automatically generated by Pandoc 2.7.2
.\"
.TH "rpn" "1" "" "" ""
.hy
.PP
RPN - Bash tool for managing a set of repositories as a bunch
.SS What it does
.PP
You have lots of repositories which you want to manipulate as a bunch
and see their status at glance
.PP
With \f[I]rpn\f[R] you can:
.IP \[bu] 2
Execute \f[I]any command\f[R] for all (or some of)* repos in your
current list
.IP \[bu] 2
See all repos state list at glance (\f[I]branch\f[R],
\f[I]ahead\f[R]/\f[I]behind\f[R]/\f[I]changes\f[R], \f[I]origin\f[R])
.IP \[bu] 2
Find files in all (or some of)* repos and (if needed) \f[I]grep\f[R]
them
.IP \[bu] 2
Create any number of lists of repositories you want to manipulate as a
bunch
.PP
* Filtering can be done by: \f[I]name\f[R], \f[I]branch\f[R],
\f[I]package\f[R], \f[I]having changes\f[R] (\f[I]or not\f[R])
.PP
\f[I]rpn\f[R] also has predefined commands to interact with
\f[I]git\f[R], \f[I]composer\f[R] and \f[I]docker\f[R] containers.
.PP
For \f[I]git\f[R] you can:
.IP \[bu] 2
Switch to branch of interest (fuzzy naming supported) with (if needed):
fetching, reseting to origin
.IP \[bu] 2
View log list
.IP \[bu] 2
Show stastus
.IP \[bu] 2
Fetch updates
.IP \[bu] 2
View last set tags
.IP \[bu] 2
Etc...
.PP
For \f[I]composer\f[R] you can:
.IP \[bu] 2
Look which repo has which verson of composer package of interest
.IP \[bu] 2
Install packages
.PP
For \f[I]docker\f[R] containers you can:
.IP \[bu] 2
Run/stop/build/restart containers (you have to rewrite at-repo commands)
.IP \[bu] 2
Run php commands in containers like \f[I]composer install\f[R] or
\f[I]bin/console doctrine:migrations:migrate\f[R]
.SS How it works
.PP
Every \f[I]rpn\f[R] command:
.IP \[bu] 2
Steps into each (can be filtered) repo item listed in
\f[I]list-directory\f[R]
.IP \[bu] 2
Run some shell code inside it
.PP
All you need is to organize your \f[I]bunch-of-repos\f[R] as a number of
soft links to repo directories (or real directories) in special
\f[I]list-directory\f[R] and point it to \f[I]rpn\f[R].
.PP
If you have more than one \f[I]bunch-of-repos\f[R] you can make special
\f[I]groups-directory\f[R] where every subfolder is a
\f[I]list-directory\f[R] described above.
.SS Installation
.IP "1." 3
Clone code to your HOME directory
.IP
.nf
\f[C]
git clone git\[at]github.com:XilefNori/rpn.git \[ti]/.rpn
\f[R]
.fi
.IP "1." 3
Add \f[I]start-up code\f[R] to your .bashrc
.IP
.nf
\f[C]
cat << EOL | sed -r \[aq]s:\[ha]\[rs]s+::\[aq] >> \[ti]/.bashrc
source \[ti]/.rpn/src/init.in
EOL
\f[R]
.fi
.IP "1." 3
Set main setting: path to your current \f[I]list-directory\f[R]
.IP
.nf
\f[C]
cat << EOL | sed -r \[aq]s:\[ha]\[rs]s+::\[aq] >> \[ti]/.bashrc
N_REPO_DIR_ROOT=\[ti]/projects/_groups/main
EOL
\f[R]
.fi
.PP
That\[aq]s it.
\f[I]rpn\f[R] is ready to use.
.SS Additional settings
.PP
If you have more than one \f[I]bunch-of-repos\f[R], you may want to set
\f[I]groups-directory\f[R]:
.IP
.nf
\f[C]
cat << EOL | sed -r \[aq]s:\[ha]\[rs]s+::\[aq] >> \[ti]/.bashrc
N_REPO_DIR_GROUPS=\[ti]/projects/_groups
EOL
\f[R]
.fi
.PP
If you want you can set some custom settings:
.IP
.nf
\f[C]
cat << EOL | sed -r \[aq]s:\[ha]\[rs]s+::\[aq] >> \[ti]/.bashrc
N_REPO_QUITE=0
N_REPO_NS_IMPORT=git,dc
N_REPO_LINE_BRANCH_LEN=30
EOL
\f[R]
.fi
.PP
\f[I]NOTICE\f[R]: \f[B]Set up your settings after executing
\f[BI]start-up code\f[B]\f[R]
.SS Commands
.PP
Rpn commands are subcommands of \f[I]rpn\f[R] util.
They are made as bash functions.
.PP
To get simple list of all available commands run:
.IP
.nf
\f[C]
rpn
\f[R]
.fi
.SS Repo state list
.PP
Run:
.IP
.nf
\f[C]
rpn l # Prints out repo-state-list
\f[R]
.fi
.PP
You will get repo-state-list (sample):
.IP
.nf
\f[C]
REPO: [ xxxxx ] 1 hour [release/v2.4.0 ..M] (git\[at]domain.com:xx/xxxxx.git)
REPO: [ xxxx ] 6 day [release/v2.3.1 \[u25B2]\[u25BC].] (git\[at]domain.com:xx/xxxx.git)
REPO: [ xxxxxxx ] 3 day [release/v2.3.1-dev ...] (git\[at]domain.com:xx/xxxxxxx.git)
REPO: [ xxxxxxx ] 7 day [release/v2.3.1-fix ...] (git\[at]domain.com:xx/xxxxxxx.git)
REPO: [ xxxxxxx ] 3 day [release/v2.3.1 ...] (git\[at]domain.com:xx/xxxxxxx.git)
REPO: [ xxxxxxxxx ] 6 day [release/v2.3.1 ..U] (git\[at]domain.com:xx/xxxxxxxxxx.git)
REPO: [ xxxx ] 3 day [release/v2.3.0 ...] (git\[at]domain.com:xx/xxxx.git)
REPO: [ xxxxxxx ] 6 day [release/v2.3.1 12.] (git\[at]domain.com:xx/xxxxxxx.git)
REPO: [ xxxxxxx ] 2 day [release/v2.3.1 ..M] (git\[at]domain.com:xx/xxxxxxx.git)
REPO: [ xxxxxx ] 9 day [release/v2.3.1 3..] (git\[at]domain.com:xx/xxxxxx.git)
REPO: [ xxxxxxxxx ] 4 week [master ...] (git\[at]domain.com:xx/xxxxxxxxx.git)
\f[R]
.fi
.PP
Description:
.IP
.nf
\f[C]
REPO: [ xxxxxxxx ] 4 week [release/v2.3.1 6\[u25BC]M] (git\[at]domain.com:xx/xxxxxxxxx.git)
\[ua] \[ua] \[ua] \[ua]\[ua]\[ua] \[ua]
repo commit branch ||changes origin
|behind
ahead
repo - project directory name
commit - last commit time ago
branch - current branch
ahead - number commits of commits ahead of remote branch (more than 9: \[u25B2])
behind - number commits of commits behind from remote branch (more than 9: \[u25BC])
changes - M - having modified files, U - having uncommitted files
origin - origin address
\f[R]
.fi
.SS Help system
.PP
To get list of available commands with short description run:
.IP
.nf
\f[C]
rpn help
\f[R]
.fi
.PP
To get help-info for specific command run:
.IP
.nf
\f[C]
rpn help <cmd> # prints help for <cmd> command
rpn <cmd> help # prints help for <cmd> command
\f[R]
.fi
.PP
If commmand does not have predefined help-info you will see its
bash-code.
.PP
To see bash-code of the command run:
.IP
.nf
\f[C]
rpn .show <cmd> # prints <cmd> bash-code
rpn <cmd> .show # prints <cmd> bash-code
\f[R]
.fi
.PP
To get this manual page run:
.IP
.nf
\f[C]
rpn man # Output format defined by \[aq]view-man-as-man\[aq] option
rpn man -m # Man-page format
rpn man -t # Text-page format (run if you don\[aq]t like man-page)
\f[R]
.fi
.SS Main command
.PP
Main \f[I]rpn\f[R] command is \f[I]do\f[R] command which executes any
bash code inside each repo in current \f[I]list-directory\f[R]
.PP
Run:
.IP
.nf
\f[C]
# Prints out repo directory and git remote name repository
rpn do \[aq]pwd; git remote\[aq]
\f[R]
.fi
.PP
\f[I]do\f[R] command has these options:
.IP
.nf
\f[C]
-- Filters --
-b <branch> - execute on repos with branch \[aq]<branch>.*\[aq]
-r <repo> - execute on with name <repo>, can be set multiple times (-r rp1 -r rp2 -r rp3)
-R <repo> - execute on all filters repos but process repo <repo> first, can be set multiple times
-p <package> - execute on repos which have composer package <package>
-g - execute on repos which have local changes
-G - execute on repos which do not have local changes
For -r|-R options you can set \[aq].\[aq] value which mean \[aq]current repo\[aq] (in $PWD)
-- Code --
-f <file> - execute file <file>
-c <code> - execute code <code>
-s - execute as standalone script file
-S - only print out code will be executed (useful for debugging)
-- Verbosity --
-Q - \[aq]quite-mode\[aq] is turned on if N_REPO_QUITE
-q - Turn on \[aq]quite-mode\[aq] (output is suppressed, and is showed only if return code is none zero)
-v - Turn on \[aq]verbose-mode\[aq]
-vv - Turn on \[aq]verbose-mode\[aq] + \[aq]debug mode\[aq] (every command in executed code is printed)
-- Output --
-l - print only repo state list
-h - print header (repo state list)
-H - print no header
-L - pipe output to less
\f[R]
.fi
.PP
Most of other commands can accept most of these options.
.PP
Many of other commands are just simple wrapper for \f[I]do\f[R] command
and look like this:
.IP
.nf
\f[C]
n-repo-git.fetch() {
n-repo-do \[dq]$\[at]\[dq] -Qs << \[aq]EOF\[aq]
printf -- \[dq][ %-${max_length}s ] fetching ...\[rs]n\[dq] \[dq]$repo\[dq]
git fetch
EOF
n-repo-l
}
\f[R]
.fi
.PP
By default commands are executed in \f[I]subshell\f[R] .
This can be overriden by \f[I]-s\f[R] option which leads to executing
code as a standalone bash script file.
.SS Filtering repositories
.PP
You can filter repos in which command will be run by:
.IP \[bu] 2
enumerating repo names (\f[I]-r repo1 -r repo2 -r repo3\f[R])
.IP \[bu] 2
setting branch mask (\f[I]-b branch\f[R])
.IP \[bu] 2
having/not-having changes in repo (\f[I]-g/-G\f[R])
.IP \[bu] 2
having some composer package installed (\f[I]-p package\f[R])
.SS List of commands
.IP
.nf
\f[C]
-- Main --
l - print repo state list
do - execute any code inside each repo directory
find - find files in current bunch-of-repos
-- Help --
man - show rpn manual (README file)
help - print command list with short description
help <cmd> - print <cmd> command help-section
<cmd> help - print <cmd> command help-section or bash-function body (if no help-section)
version - print version
-- System --
cd <repo> - cd to repo directory
\&.show <cmd> - print <cmd> bash-function body
<cmd> .show - print <cmd> bash-function body
\&.update - update rpn code from github
\&.cd-group <grp> - cd to <grp> directory
\&.dirs - print directories in current \[aq]list-directory\[aq]
\&.hint.<xxxx> - create and print \[aq]hint-list\[aq] <xxxx>
-- Config --
cfg - print environment configuration
root - print or set current \[aq]list-directory\[aq]
-- Composer packages --
package <name> - print repo name and package version for repos which has package <name>
package.install - install composer packages
-- Git --
git.switch - switch to branch (release/v4 -> release/v4.3.1)
git.last-tags - show last created tags
git.origin - reset current local <branch> to origin/<branch>
git.fetch - fetch
git.log - show log
git.di - show diff
git.info - show [header, git status, git log -1]
git.master - reset to master
git.st - show git status
-- Docker --
dc.build - build docker containers
dc.restart - restart docker containers
dc.stop - stop docker containers
dc.up - up docker containers
dc.env - show diff between .env and .env.dist
-- Symfony inside docker (commands executed inside docker containers for each repo) --
code.clear-cache - clear cache for symfony project
code.install - full install composer packages (with \[aq]scripts\[aq] and \[aq]platform-requirements\[aq])
code.migration - run symfony migration
code.prepare - code.(clear-cache + install + migration)
\f[R]
.fi
.SS Command completion
.PP
\f[I]rpn\f[R] is trying to support \f[I]tab-completion\f[R] anywhere it
possibly can
.IP
.nf
\f[C]
# -- Common completions --
rpn <tab> # Will propose user command
rpn .<tab> # Will propose system command (started with a dot \[aq].\[aq])
rpn help <tab> # Will propose command with help-section or standalone help-section
rpn cmd -<tab> # Will propose cmd-option
rpn cmd -b <tab> # Will propose list of all current branches
rpn cmd -r <tab> # Will propose list of repos
rpn cmd -R <tab> # Will propose list of repos
rpn cmd -p <tab> # Will propose list of packages
# -- Command specific completions --
rpn cd <tab> # Will propose list of all repos
rpn find <tab> # Will propose list of files (list is configured by find-hint option)
rpn package <tab> # Will propose list of all possible packages
rpn git.switch <tab> # Will propose list of all possible branches
\f[R]
.fi
.SS Command completion caching
.PP
Because generation of \f[I]hint-lists\f[R] can be time consuming, heavy
\f[I]hint-lists\f[R] are cached in files in
\f[I]$N_REPO_DIR_ROOT/.cache\f[R] subdirectory.
.PP
\f[I]hint-lists\f[R] generation commands are system and prefixed with
\f[I].hint\f[R] prefix.
.PP
For example for package list it is: \f[I]rpn .hint.package\f[R]
.PP
Cache files are kept due to \f[I]cache-lifetime\f[R] setup in cache-*
parameters in seconds
.PP
For example \f[I]cache-package\f[R]=600 which means than
\f[I]cache-file\f[R] with package-list will be regenerated after 600
seconds since it was (re)created last time.
.PP
To force recreation of \f[I]cache-file\f[R] you should run corresponding
\f[I]hint-command\f[R]
.PP
You can see current cache settings by running:
.IP
.nf
\f[C]
rpn cfg cache
\f[R]
.fi
.SS Command namespace import
.PP
If you do not like to enter command prefixes such as \f[I]git.\f[R] or
\f[I]dc.\f[R] and want to type \f[I]rpn fetch\f[R] instead of \f[I]rpn
git.fetch\f[R] you can import \f[I]command-namespace\f[R] to global
namespace.
.PP
This is done by setting configuration parameter \f[I]ns-import\f[R].
.PP
Namespaces are delimited by comma:
.IP
.nf
\f[C]
N_REPO_NS_IMPORT=git,dc
\f[R]
.fi
.PP
Once you did it you can run: \f[I]rpn switch\f[R] instead of \f[I]rpn
git.switch\f[R].
.SS Configuration
.PP
Configuration of \f[I]rpn\f[R] is made by environment variables with
prefix \f[I]N_REPO\f[R]
.PP
To see all current configuration, run:
.IP
.nf
\f[C]
rpn cfg # Output format defined by \[aq]view-config-as-env\[aq]
rpn cfg -p # Configuration parameters format
rpn cfg -e # Environment variables format
\f[R]
.fi
.PP
Parameters are just more short format for environment variables:
.IP
.nf
\f[C]
dir-root <=> N_REPO_DIR_ROOT
\f[R]
.fi
.PP
To see only group of interest configuration, run:
.IP
.nf
\f[C]
rpn cfg cache # Show cache configuration
rpn cfg dir # Show dir configuration
\f[R]
.fi
.PP
To set configuration parameter:
.IP
.nf
\f[C]
N_REPO_CACHE_BRANCHES=120 # Set environment variable
rpn cfg cache-branches 120 # Set parameter with \[aq]cfg\[aq] command
\f[R]
.fi
.PP
\f[I]NOTICE\f[R]: \f[B]Set up your configuration after executing
\f[BI]start-up code\f[B]\f[R]
.SS Configuration parameters description
.IP
.nf
\f[C]
-- Directories --
dir-groups path to _groups-directory_
dir-root path to current _list-directory_
dir-install path to rpn dist installed
-- Commands parameters --
ns-import string of command namespaces imported to global namespace delimited by comma, sample: \[aq]git,dc\[aq]
quite default output mode is _quite-mode_ (output is suppressed, and is showed only if return code is none zero)
-- Completion caches life-times in seconds --
cache-branches all known branches [in all repos]
cache-branches-cur current branches [in all repos]
cache-find-hint file names [in all repos]
cache-package composer package names [in all repos]
-- Repo state list parameters --
line-ahead-sign sing for ahead commits (when exceeds 9)
line-behind-sign sing for behind commits (when exceeds 9)
line-branch-len max length of branch name
line-repo-len max length of repo name
line-long long format of _repo-state-list_ (includes: origin or last commit message)
line-color-name color of repo name
line-color-ahead color of _ahead_ symbol
line-color-behind color of _behind_ symbol
line-color-modified color of _modified_ symbol
line-color-untracked color of _untracked_ symbol
line-color-mod-untracked color of _modified and untracked_ symbol
-- Find command parameters --
find-depth default -maxdepth of searching
find-hint list of directories in repo where to find files for _tab-completion_
find-short print short file name (from repo subdirectory)
-- View config --
view-config-as-env show configuration as ENVIRONMENT_VARIABLES (or config-parameters)
view-man-as-man show manual as man page (filter README.md with _pandoc_ and _nroff_)
\f[R]
.fi
.SS Default Configuration
.IP
.nf
\f[C]
dir-groups \[ti]/projects/_groups
dir-root \[ti]/projects/_groups/main
dir-install <path to rpn dist installed>
ns-import
quite 1
cache-branches 60
cache-branches-cur 60
cache-find-hint 600
cache-package 600
line-color-ahead $\[aq]\[rs]E[0;32m\[aq]
line-color-behind $\[aq]\[rs]E[0;31m\[aq]
line-color-modified $\[aq]\[rs]E[0;94m\[aq]
line-color-mod-untracked $\[aq]\[rs]E[0;33m\[aq]
line-color-name $\[aq]\[rs]E[0;94m\[aq]
line-color-untracked $\[aq]\[rs]E[0;33m\[aq]
line-ahead-sign \[u25B2]
line-behind-sign \[u25BC]
line-branch-len 25
line-repo-len 15
line-long 1
find-depth 4
find-hint ([0]=\[dq]config\[dq] [1]=\[dq].docker\[dq])
find-short 1
view-config-as-env 0
view-man-as-man 0
\f[R]
.fi
.SS Naming history
.PP
There was a tool for repo manipulating called \f[I]rp\f[R] which is
abbreviation of \f[I]repo\f[R].
Then I made \f[I]n-repo\f[R] for manipulating a \f[I]bunch-of-repos\f[R]
which leads us to \f[I]rpn\f[R].