-
Notifications
You must be signed in to change notification settings - Fork 3
/
cobib.1
1110 lines (1103 loc) · 38.9 KB
/
cobib.1
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
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.TH COBIB 1 2024-12-15 v5.2.3
.SH NAME
coBib \- Console-based Bibliography Management
.SH SYNOPSIS
.B cobib
[\fB\-\-version\fR]
[\fB\-h\fR|\fB\-\-help\fR]
[\fB\-v\fR|\fB\-\-verbose\fR]
[\fB\-c\fR|\fB\-\-config\fR \fI<path>\fR]
\fB<subcommand>\fR [\fI<args>\fR]
.SH DESCRIPTION
coBib is a console-based bibliography manager written in Python.
It maintains a plain-text database of literature data in YAML format at
\fI$HOME/.local/share/cobib/literature.yaml\fR.
.PP
coBib provides a variety of \fBSUBCOMMANDS\fR through which you may
investigate and manage the database.
For easy of use it also comes with a textual-based \fBTUI\fR which is
automatically started when no other subcommand is found (more information is
provided in that section).
.PP
coBib also provides some "meta"-commands. These are expained in the \fBSHELL
UTILITIES\fR section.
.SH OPTIONS
.TP
.BR \-\-version
Prints the version information and exits.
.TP
.BR \-h ", " \-\-help
Prints a help message and exits.
.TP
.BR \-v ", " \-\-verbose
Increases the verbosity level of the logging. This option may be provided up to
two times (increasing the logging to \fIinfo\fR and \fIdebug\fR, respectively).
By default, the verbosity of coBib's CLI is set to \fIwarning\fR but if the TUI
is started, logging will be increased to \fIinfo\fR and redirected to
\fIconfig.logging.logfile\fR.
.TP
.BR \-p ", " \-\-porcelain
Switches the output that will be printed to the terminal to "porcelain" mode.
This is meant to be useful for parsing and testing purposes.
.TP
.BR \-c ", " \-\-config " " \fI<path>\fR
Run with an alternate configuration file at \fI<path>\fR.
.TP
.BR \-l ", " \-\-log " " \fI<path>\fR
Run with an alternate log file at \fI<path>\fR.
.SH SUBCOMMANDS
All subcommands listed below also provide the \fI\-h\fR and \fI\-\-help\fR
options which provide additional information for each subcommand.
.TP
.B cobib init \fI<args>\fR
Initializes the literature database.
The path to this file can be configured in the \fIDATABASE\fR section of the
configuration file (see also \fBCONFIGURATION\fR).
The only available argument is:
.PP
.in +8n
.BR \-g ", " \-\-git
.in +4n
Initializes coBib's integrated history tracking through git.
This command will preserve any existing database file, but it is a good idea to
make a backup before doing this, just in case.
Note, that in order to use this functionality you must also enable the
\fIDATABASE/git\fR configuration option (see also \fBCONFIGURATION\fR).
Also be sure to at least set a \fIname\fR and \fIemail\fR in the git config!
.TP
.B cobib git \fI<args>\fR ...
.in +4n
Passes through to \fIgit\fR to run operations on the underlying database.
All arguments provided after \fIgit\fR are forwarded without being changed.
.TP
.B cobib add \fI<args>\fR ...
Adds a new entry to the database.
The positional arguments may be used to provide \fItags\fR to associate with the
newly added entries.
The \fI<args>\fR may be any of the following:
.PP
.in +8n
.BR \-a ", " \-\-arxiv " " \fI<arxiv\ id>\fR
.in +4n
Adds an entry specified by the \fIarXiv\fR id.
.PP
.in +8n
.BR \-b ", " \-\-bibtex " " \fI<path>\fR
.in +4n
Adds the bibliography data from the \fIBibLaTex\fR file at the provided path.
.PP
.in +8n
.BR \-d ", " \-\-doi " " \fI<doi>\fR
.in +4n
Adds an entry specified by the \fIDOI\fR.
.PP
.in +8n
.BR \-i ", " \-\-isbn " " \fI<ISBN>\fR
.in +4n
Adds an entry specified by the \fIISBN\fR.
.PP
.in +8n
.BR \-\-url " " \fI<URL>\fR
.in +4n
Attempts to extract an entry from the \fI<URL>\fR.
.PP
.in +8n
.BR \-y ", " \-\-yaml " " \fI<path>\fR
.in +4n
Adds the bibliography data from the \fIYAML\fR file at the provided path.
The only supported YAML format is that of a coBib database file.
.PP
.in +8n
.BR \-l ", " \-\-label " " \fI<label>\fR
.in +4n
Store the newly added entry under the specified \fIlabel\fR.
.PP
.in +8n
.BR \-f ", " \-\-file " " \fI<path>\fR
.in +4n
Associate the newly added entry with the \fIfile\fR at the provided path.
As of version 2.5 you can specify multiple files, too.
.PP
.in +8n
.BR \-p ", " \-\-path " " \fI<path>\fR
.in +4n
Overwrites the location for the automatically downloaded file. If not specified,
this setting defaults to \fIconfig.utils.file_downloader.default_location\fR.
.PP
.in +8n
.BR \-\-disambiguation " " \fI<reply>\fR
.in +4n
Sets the reply for the interactive prompt if an addition needs to be
disambiguated. The possible values for \fI<reply>\fR are the following:
.in +4n
.IR keep
to keep the existing entry
.in +0n
.IR replace
to replace the existing entry
.in +0n
.IR update
to update the existing entry
.in +0n
.IR disambiguate
to disambiguate the new label from the existing one by adding a label suffix
(see also \fIconfig.database.format.label_suffix\fR)
.PP
.in +8n
.BR \-\-skip\-download
.in +4n
Skips attempting to automatically download an associated file for the entry.
This takes precedence over the \fIconfig.commands.add.skip_download\fR setting.
.PP
.in +8n
.BR \-\-force\-download
.in +4n
Forces attempting to automatically download an associated file for the entry.
This takes precedence over the \fIconfig.commands.add.skip_download\fR setting.
.TP
.B cobib delete \fI<label>\fR
Deletes the entry with the given \fIlabel\fR.
.PP
.in +8n
.BR \-\-preserve\-files
.in +4n
If specified, associated files will be preserved and \fInot\fR deleted.
This takes precedence over the \fIconfig.commands.delete.preserve_files\fR
setting.
.PP
.in +8n
.BR \-\-no\-preserve\-files
.in +4n
If specified, associated files will \fInot\fR be preserved.
This takes precedence over the \fIconfig.commands.delete.preserve_files\fR
setting.
.TP
.B cobib edit \fI<label>\fR
Opens the entry with the given \fIlabel\fR in an external editor.
The entry is copied verbatim in \fIYAML\fR format from and to the database file.
The editor respects the \fI$EDITOR\fR environment variable unless overwritten by
\fIconfig.commands.edit.editor\fR. It will fallback to \fIvim\fR if neither is
configured.
.PP
.in +8n
.BR \-a ", " \-\-add " " \fI<path>\fR
.in +4n
Allows editing a non-existing label to manually add it to the database.
.PP
.in +8n
.BR \-\-preserve\-files
.in +4n
If specified, associated files will be preserved and \fInot\fR be renamed if the
edit happens to rename the entry. This takes precedence over the
\fIconfig.commands.edit.preserve_files\fR setting.
.PP
.in +8n
.BR \-\-no\-preserve\-files
.in +4n
If specified, associated files will \fInot\fR be preserved and be renamed if the
edit happens to rename the entry. This takes precedence over the
\fIconfig.commands.edit.preserve_files\fR setting.
.TP
.B cobib modify \fI<modification>\fR \fI<args>\fR ...
Applies a modification to multiple entries at once.
The positional arguments may be used to provide \fBFILTERS\fR which the entries
must match in order to be modified \fIor\fR to provide a list of labels of the
entries which are to be modified (this requires the \fI-s\fR flag to be set).
The \fI<args>\fR may be any of the following:
.PP
.in +8n
.BR \fI<modification>\fR
.in +4n
The modification must be provided in the format \fI<field>:<value>\fR and will
set the field of all selected entries to the given value.
As of v3.2.0 the \fI<value>\fR is interpreted as an "f"-string. This means you
can even use placeholder variables and perform simple operations on them. The
available variables depend on the entry which you are modifying as they are
inferred from its stored data. For more information on "f"-strings refer to
section 2.4.3 of https://docs.python.org/3/reference/lexical_analysis.html
.PP
.in +8n
.BR \-\-dry
.in +4n
When this flag is given, the modify command runs in \fIdry\fR mode. This means,
the applied modifications are printed to stdout rather than applied directly.
This allows easy prototyping of modifications to prevent errors during large
bulk modifications.
.PP
.in +8n
.BR \-a ", " \-\-add
.in +4n
Specifying this flag will add the modification's value to the specified field of
the entry rather than overwriting it. In doing so, strings will be concatenated
with\fBOUT\fR any spaces, lists will be appended to, numbers will be added, and
anything else will be converted to a string field.
If the field did not exist previously, it will simply be initialized with the
new value.
.PP
.in +8n
.BR \-r ", " \-\-remove
.in +4n
Specifying this flag will remove the modification's value from the specified
field of the entry rather than overwriting it. In doing so, items will be
removed from lists, numbers will be subtracted, and anything else will be left
unchanged.
.PP
.in +8n
.BR \-s ", " \-\-selection
.in +4n
This boolean flag enables the \fIselection\fR mode in which the positional args
are interpreted as a list of labels which are to be exported. The name for this
argument is a result of the TUI's selection interface.
.PP
.in +8n
.BR \-\-preserve\-files
.in +4n
If specified, associated files will be preserved and \fInot\fR be renamed if
the modification happens to rename the entry. This takes precedence over the
\fIconfig.commands.modify.preserve_files\fR setting.
.PP
.in +8n
.BR \-\-no\-preserve\-files
.in +4n
If specified, associated files will \fInot\fR be preserved and be renamed if
the modification happens to rename the entry. This takes precedence over the
\fIconfig.commands.modify.preserve_files\fR setting.
.TP
.B cobib note \fI<label>\fR \fI<action>\fR
Applies an action to the note of the provided entry. The available \fIactions\fR
are:
.PP
.in +8n
.BR show
.in +4n
Shows the note's contents.
.PP
.in +8n
.BR edit
.in +4n
Opens the note file in the \fIconfig.commands.edit.editor\fR for editing.
.PP
.in +8n
.BR delete
.in +4n
Deletes the note.
.TP
.B cobib review \fI<field>\fR \fI<args>\fR ...
Performs an interactive review of your database.
You can optionally review one or more specific fields of the entries by
providing the field names as arguments to the command.
The positional arguments may be used to provide \fBFILTERS\fR which the entries
must match in order to be reviewed \fIor\fR to provide a list of labels of the
entries which are to be reviewed (this requires the \fI-s\fR flag to be set).
For every entry that is being reviewed, multiple actions are possible. These
include:
.TP
.in +8n
.BR edit
.in +4n
Opens the current entry in an external editor.
.TP
.in +8n
.BR done
.in +4n
Marks the current entry as fully reviewed.
.TP
.in +8n
.BR skip
.in +4n
Skips the current entry for this review.
.TP
.in +8n
.BR context
.in +4n
Requests additional context and updates the preview to contain all the
information stored in the entry. This action is only available when no context
has been requested yet and the previewed fields are being filtered in the first
place.
.TP
.in +8n
.BR finish
.in +4n
Finishes the review early (even if some entries have not been shown yet). See
\fI\-\-resume\fR for how to resume a previously started review process.
.TP
.in +8n
.BR inline <field>
.in +4n
Edits a specific field in-line. When reviewing a single field, you can simply
type \fIinline\fR. When reviewing more than one, you need to specify which field
to edit like so \fIinline <field>\fR. This is a highly experimental feature so
please be aware of bugs and report any issues or suggestions online:
https://gitlab.com/cobib/cobib/-/issues/new
.TP
.in +8n
The \fI<args>\fR to the \fBreview\fR command may be any of the following:
.PP
.in +8n
.BR \-c ", " \-\-context
.in +4n
.PP
Enforces that context will be provided for every entry.
.in +8n
.BR \-r ", " \-\-resume " " \fI<SHA>\fR
.in +4n
If you finished a review early (see `finish` above) you can use this argument to
continue where you left. This option takes a git commit identifier as its
argument so you should either find the SHA of the auto-commit of the review that
you would like to continue (see also the \fIgit\fR command), or if you know that
it is (for example) the last thing that you did, you can simply use \fRHEAD\fR.
.PP
.in +8n
.BR \-d ", " \-\-done " " \fI<labels>\fR
.in +4n
Can supply a list of entry labels which will be considered as already reviewed
and therefore skipped. Thus, this has a higher precedence than the provided
\fBFILTERS\fR and can be used to resume a previously started review process. If
you have the \fIgit\fR integration enabled, you will likely not use this
argument manually. Instead, refer to the \fI\-\-resume\fR argument.
.PP
.in +8n
.BR \-s ", " \-\-selection
.in +4n
This boolean flag enables the \fIselection\fR mode in which the positional args
are interpreted as a list of labels which are to be exported. The name for this
argument is a result of the TUI's selection interface.
.TP
.B cobib undo \fI<args>\fR
If you enabled the git-integration of coBib (available since v2.6.0) you can
undo the changes done to your database file by commands such as add, edit and
delete. See also \fIDATABASE/git\fR in the \fBCONFIGURATION\fR section for more
information.
.PP
.in +8n
.BR \-f ", " \-\-force
.in +4n
Overwrites the check for an auto-committed change. Thus, the undo command will
now undo the last commit with a message that does not start with "Undo".
.TP
.B cobib redo
If you enabled the git-integration of coBib (available since v2.6.0) you can
reapply the last undone changes (see above). See also \fIDATABASE/git\fR in the
\fBCONFIGURATION\fR section for more information.
.TP
.B cobib open \fI<label>\fR
Opens any associated \fIfile\fR of the entry with the given \fIlabel\fR.
If multiple files are associated with the entry, the user can choose which
file(s) to open through an interactive menu.
.PP
.in +8n
.BR \-f ", " \-\-field " " \fI<choice>\fR
.in +4n
Specifies the field type to open. This bypasses the interactive prompt if
multiple actionable fields are found. The choice can be either \fIall\fR or any
of the values configured in \fIconfig.commands.open.fields\fR.
.TP
.B cobib show \fI<label>\fR
Prints the entry with the given \fIlabel\fR in \fIBibLaTex\fR format to stdout.
.TP
.B cobib list \fI<args>\fR
Lists all entries of the database in a basic table format to stdout which match
the specified \fBFILTERS\fR (more information is provided in that section).
Additionally, the following \fI<args>\fR are also allowed:
.PP
.in +8n
.BR \-s ", " \-\-sort " " \fI<field>\fI
.in +4n
Specify the entry field to use as the \fIsorting column\fR of the table.
.PP
.in +8n
.BR \-r ", " \-\-reverse
.in +4n
Reverses the sorting order.
.PP
.in +8n
.BR \-l ", " \-\-limit " " \fI<int>\fI
.in +4n
Limits the number of displayed results to the specified number.
.PP
.in +8n
.BR \-i ", " \-\-ignore\-case
.in +4n
Makes the entry matching case-insensitive.
This takes precedence over the \fIconfig.commands.list_.ignore_case\fR setting.
.PP
.in +8n
.BR \-I ", " \-\-no\-ignore\-case
.in +4n
Makes the entry matching case-sensitive.
This takes precedence over the \fIconfig.commands.list_.ignore_case\fR setting.
.PP
.in +8n
.BR \-\-decode\-latex
.in +4n
Makes the entry matching decode all LaTeX sequences.
This takes precedence over the \fIconfig.commands.list_.decode_latex\fR setting.
.PP
.in +8n
.BR \-\-no\-decode\-latex
.in +4n
Makes the entry matching preserve all LaTeX sequences.
This takes precedence over the \fIconfig.commands.list_.decode_latex\fR setting.
.PP
.in +8n
.BR \-\-decode\-unicode
.in +4n
Makes the entry matching decode all Unicode characters.
This takes precedence over the \fIconfig.commands.list_.decode_unicode\fR
setting.
.PP
.in +8n
.BR \-\-no\-decode\-unicode
.in +4n
Makes the entry matching preserve all Unicode characters.
This takes precedence over the \fIconfig.commands.list_.decode_unicode\fR
setting.
.PP
.in +8n
.BR \-z ", " \-\-fuzziness " " \fI<int>\fI
.in +4n
Specifies how many fuzzy errors to allow during entry matching.
The default value is 0 but can be configured via
\fIconfig.commands.list_.fuzziness\fR.
.PP
.in +8n
.BR \-x ", " \-\-or
.in +4n
Concatenate the filters using logical \fIOR\fR rather than the default
\fIAND\fR.
.TP
.B cobib search \fI<query>\fR \fI<args>\fR ...
Searches the database recursively (i.e. including any associated files) for the
specified queries (if multiple are given, these will be searched independently).
The positional arguments may be used to provide \fBFILTERS\fR which the entries
must match in order to be included in the export.
Additionally, the following \fI<args>\fR are also allowed:
.PP
.in +8n
.BR \-c ", " \-\-context " " \fI<int>\fI
.in +4n
Specify the number of context lines to provide for each match.
The default value is 1 but can be configured via
\fIconfig.commands.search.context\fR.
.PP
.in +8n
.BR \-i ", " \-\-ignore\-case
.in +4n
Makes the search case-insensitive.
This takes precedence over the \fIconfig.commands.search.ignore_case\fR setting.
.PP
.in +8n
.BR \-I ", " \-\-no\-ignore\-case
.in +4n
Makes the search case-insensitive.
This takes precedence over the \fIconfig.commands.search.ignore_case\fR setting.
.PP
.in +8n
.BR \-l ", " \-\-decode\-latex
.in +4n
Makes the search decode all LaTeX sequences.
This takes precedence over the \fIconfig.commands.search.decode_latex\fR
setting.
.PP
.in +8n
.BR \-L ", " \-\-no\-decode\-latex
.in +4n
Makes the search preserve all LaTeX sequences.
This takes precedence over the \fIconfig.commands.search.decode_latex\fR
setting.
.PP
.in +8n
.BR \-u ", " \-\-decode\-unicode
.in +4n
Makes the search decode all Unicode characters.
This takes precedence over the \fIconfig.commands.search.decode_unicode\fR
setting.
.PP
.in +8n
.BR \-U ", " \-\-no\-decode\-unicode
.in +4n
Makes the search preserve all Unicode characters.
This takes precedence over the \fIconfig.commands.search.decode_unicode\fR
setting.
.PP
.in +8n
.BR \-z ", " \-\-fuzziness " " \fI<int>\fI
.in +4n
Specifies how many fuzzy errors to allow during search.
The default value is 0 but can be configured via
\fIconfig.commands.search.fuzziness\fR.
.PP
.in +8n
.BR \-\-skip\-files
.in +4n
Skips searching the associated files.
This takes precedence over the \fIconfig.commands.search.skip_files\fR setting.
.PP
.in +8n
.BR \-\-include\-files
.in +4n
Enables searching the associated files.
This takes precedence over the \fIconfig.commands.search.skip_files\fR setting.
.PP
.in +8n
.BR \-\-skip\-notes
.in +4n
Skips searching the associated notes.
This takes precedence over the \fIconfig.commands.search.skip_notes\fR setting.
.PP
.in +8n
.BR \-\-include\-notes
.in +4n
Enables searching the associated notes.
This takes precedence over the \fIconfig.commands.search.skip_notes\fR setting.
.TP
.B cobib export \fI<args>\fR ...
Exports the database.
The positional arguments may be used to provide \fBFILTERS\fR which the entries
must match in order to be included in the export \fIor\fR to provide a list of
labels of the entries which are to be exported (this requires the \fI-s\fR flag
to be set).
The \fI<args>\fR may be any of the following:
.PP
.in +8n
.BR \-b ", " \-\-bibtex " " \fI<path>\fR
.in +4n
Export the entries to a \fIBibLaTex\fR file at the specified path.
.PP
.in +8n
.BR \-z ", " \-\-zip " " \fI<path>\fR
.in +4n
Export a \fIBibLaTex\fR file of the entries and all of the associated files into
a single \fIZIP\fR file at the specified path.
.PP
.in +8n
.BR \-s ", " \-\-selection
.in +4n
This boolean flag enables the \fIselection\fR mode in which the positional args
are interpreted as a list of labels which are to be exported. The name for this
argument is a result of the TUI's selection interface.
.PP
.in +8n
.BR \-a ", " \-\-abbreviate
.in +4n
Causes all Journal names to be abbreviated. For this option to take effect, a
list of abbreviations must be configured via
\fIconfig.utils.journal_abbreviations\fR.
.PP
.in +8n
.BR \-\-dotless
.in +4n
Works in conjunction with the \fIabbreviate\fR argument in order to remove
punctuation from the journal abbreviations.
.TP
.B cobib import \fI<args>\fR ...
Imports entries from another bibliography manager. You usually only need to run
this command once.
The \fI<args>\fR may be any of the following:
.PP
.in +8n
.BR \-\-skip\-download
.in +4n
Skips downloading of attachments encountered during the library import.
This takes precedence over the \fIconfig.commands.import_.skip_download\fR
setting.
.PP
.in +8n
.BR \-\-force\-download
.in +4n
Forces downloading of attachments encountered during the library import.
This takes precedence over the \fIconfig.commands.import_.skip_download\fR
setting.
.PP
.in +8n
Furthermore you can specify one of the following sources from which to import
your library. Each of those sources can optionally take further arguments via
positional arguments following a \fI--\fR separator.
.PP
.in +8n
.BR \-\-zotero " -- " \fI<args>\fR
.in +4n
The \fI<args>\fR may be any of the following:
.PP
.in +12n
.BR \-\-no-cache
.in +8n
Disabling loading or storing of cached OAuth authentication tokens.
.PP
.in +12n
.BR \-\-user-id " " \fI<user\ ID>\fR
.in +8n
Provide a custom Zotero user ID. If this is a publicly accessible library, no
API key is required. Otherwise you must also use the following argument.
.PP
.in +12n
.BR \-\-api-key " "\fI<API\ key>\fR
.in +8n
Provide a custom Zotero API key.
.TP
.B cobib lint
Lints the database file for potential points of formatting improvements.
.PP
.in +8n
.BR \-f ", " \-\-format
.in +4n
If you provide this option, coBib will automatically format your database to
resolve all found lint messages.
.TP
.B cobib unify_labels
Updates all entry labels in your database to follow the default naming pattern.
.PP
.in +8n
.BR \-a ", " \-\-apply
.in +4n
If you provide this option, coBib will actually apply the updates rather than
preview them in dry-mode.
.SH FILTERS
In order to limit the output of the \fIlist\fR, \fImodify\fR, \fIsearch\fR, and
\fIexport\fR commands you can apply additional filters via keyword arguments.
Their availability depends on your database since they are added to the argument
parser at runtime.
However, you can find a full list for your specific case with \fIcobib list
\-\-help\fR.
.PP
The general syntax for filtering is the following
.in +8n
[\fB++\fR|\fB\-\-\fR]\fB<field>\fR \fI<value>\fR
.in
which is to be understood as the following:
When the keyword argument is started with \fB++\fR the entry must positively
\fImatch\fR this filter; if started with \fB\-\-\fR it must \fINOT\fR match.
The \fB<field>\fR may be any available field in your database.
It should be noted, that this string is matched exactly which means no plurals
are allowed.
The \fI<value>\fR finally specifies what is matched against. As of version
v3.2.0 this value gets interpreted as a regex pattern, enabling powerful filter
matching.
.PP
In general, multiple filters provided to the \fIlist\fR and \fIexport\fR
commands are combined with logical \fIAND\fR.
This may be overwritten by adding the \fI\-x\fR or \fI\-\-or\fR arguments as
described in the arguments section of the \fIlist\fR command.
More generally, you may also provide any of the other arguments of the
\fIlist\fR command allowing you to sort and limit the number of entries which
you want to further act on.
.SH EXAMPLES
This section provides a few examples of \fBFILTERS\fR as described above.
.TP
.B cobib list ++year 2020
Lists only entries which were published in 2020.
.TP
.B cobib list --tags chemistry
Lists only entries without the `chemistry` tag.
.TP
.B cobib list ++year 2019 ++tags quantum
Lists only entries with the `quantum` tag from the year 2019.
.TP
.B cobib list -x ++year 2019 ++year 2020
Lists only entries published in 2019 or 2020.
.SH TUI
The textual-based TUI is started automatically when no other subcommand is
supplied, i.e. by simply running \fBcobib\fR.
By default, it lists all entries of the database in a scrollable view and
displays the bibtex-representation of the entry under the cursor in a side
panel. You can scroll using vim-like keybindings \fIh,j,k,l\fR or the arrow
keys.
The following key bindings are available:
.TP
.BR q " " quit
Quits the TUI.
.TP
.BR ? " " help
Opens a small window providing help for the key bindings.
.TP
.BR _ " " layout
Toggles between a horizontally and vertically split layout.
.TP
.BR SPACE " " folds
When displaying search results, toggles the visibility of any tree node.
.TP
.BR : " " prompt
Opens a command prompt allowing the user to execute an arbitrary coBib CLI
command.
.TP
.BR v " " select
Adds the current label to the \fIselection\fR.
.TP
.BR / " " search
Opens a search prompt and views the results in an interactive tree structure.
.TP
.BR digit " " preset
Immediately seledcts the preset filter given by that digit (0 = reset).
.TP
.BR a " " add
Opens a command prompt which allows running the \fBadd\fR command as if outside
of the TUI.
.TP
.BR d " " delete
Deletes the current (or \fIselected\fR) label(s).
.TP
.BR e " " edit
Opens the current label in an external editor.
.TP
.BR f " " filter
Allows adding filters to the list of displayed entries.
.TP
.BR i " " import
Opens a command prompt which allows running the \fBimport\fR command as if
outside of the TUI.
.TP
.BR m " " modify
Opens a command prompt which allows running the \fBmodify\fR command as if
outside of the TUI. If a \fIselection\fR is present, the \fI-s\fR argument will
be set automatically.
.TP
.BR o " " open
Opens the current (or \fIselected\fR) label(s).
.TP
.BR p " " preset
Allows selecting a preset filter (see \fIconfig.tui.preset_filters\fR).
.TP
.BR r " " redo
Reapplies the last undone change.
This requires the git-integration (since v2.6.0) to be enabled!
.TP
.BR s " " sort
Allows sorting the list view.
.TP
.BR u " " undo
Undoes the last auto-committed change to the database file.
This requires the git-integration (since v2.6.0) to be enabled!
.TP
.BR x " " export
Opens a command prompt which allows running the \fBexport\fR command as if
outside of the TUI. If a \fIselection\fR is present, the \fI-s\fR argument will
be set automatically.
Opens a small window providing help for the key bindings.
.SH CONFIGURATION
Since version 3.0, coBib can be configured directly via \fIPython\fR. To do so,
you must place the configuration file at \fI$HOME/.config/cobib/config.py\fR.
If you don't have a configuration file yet, you can get started by copying the
well-documented example configuration to the right location via:
.in +4n
\fIcobib example_config > ~/.config/cobib/config.py\fR
.in -4n
If you do have an old configuration file (prior to v3.0) and would like some
guidance on how to migrate it, please read this short blog post of mine:
https://mrossinek.gitlab.io/programming/cobibs-new-configuration/
.PP
Since v3.5, coBib also respects the \fICOBIB_CONFIG\fR environment variable.
With this you can either specify a custom path to your configuration file or
disable the loading of a configuration file entirely by setting it to one of the
following values: \fI"", 0, "f", "false", "nil", "none"\fR.
.PP
The following section summarizes the syntax and all possibly settings, for
completeness.
.TP
.BR Configuration " " Syntax
Internally, coBib's configuration is nothing but a (nested) Python dataclass.
Thus, after importing the config with
.in +4n
\fIfrom cobib.config import config\fR
.in -4n
it is very straight forward to change any setting by simply changing the value
of an attribute. For example:
.in +4n
\fIconfig.database.git = True\fR
.in -4n
.PP
.BR LOGGING
.TP
.IR config.logging.cache = '~/.cache/cobib/cache'
This settings sets the path to the default cache file.
.TP
.IR config.logging.logfile = '~/.cache/cobib/cobib.log'
This setting sets the path to the default logfile. This setting can be
overwritten at runtime using the \fI--logfile\fR command-line argument.
.TP
.IR config.logging.version = '~/.cache/cobib/version'
In this file, the last run version of coBib gets cached. After an update, coBib
automatically prints the newest section of the Changelog. To disable this
functionality entirely, set this option to \fINone\fR.
.PP
.BR COMMANDS
.TP
.IR config.commands.add.skip_download = False
Specifies whether to skip the attempt of downloading PDF files of added entries.
.TP
.IR config.commands.delete.confirm = True
Specifies whether or not to prompt for confirmation before deleting an entry.
.TP
.IR config.commands.delete.preserve_files = False
Specifies whether associates files should be preserved during deletion.
.TP
.IR config.commands.edit.default_entry_type = 'article'
This setting indicates the default entry type which will be used for manually
entered entries.
.TP
.IR config.commands.edit.editor = $EDITOR " if available else " 'vim'
This setting can be used to overwrite the external editor used for manual
editing of database entries. It defaults to the environment variable
\fI$EDITOR\fR and falls back to \fIvim\fR if that is not set either.
.TP
.IR config.commands.edit.preserve_files = False
Specifies whether associates files should be preserved during renaming.
.TP
.IR config.commands.import_.skip_download = False
Specifies whether to skip downloading of attachments encountered during the
library import.
.TP
.IR config.commands.list_.default_columns = ['label',\ 'title']
Specifies the default columns displayed during the \fIlist\fR command.
.TP
.IR config.commands.list_.ignore_case = False
Specifies whether filter matching should be performed case-insensitive.
.TP
.IR config.commands.list_.decode_unicode = False
Specifies whether filter matching should decode all Unicode characters.
.TP
.IR config.commands.list_.decode_latex = False
Specifies whether filter matching should decode all LaTeX sequences.
.TP
.IR config.commands.list_.fuzziness = 0
Specifies the amount of fuzzy errors to allow for filter matching. Using this
feature requires the optional \fIregex\fR dependency to be installed.
.TP
.IR config.commands.modify.preserve_files = False
Specifies whether associates files should be preserved during renaming.
.TP
.IR config.commands.note.default_filetype = 'txt'
Specifies the default filetype to use for associated notes.
.TP
.IR config.commands.open.command = 'xdg-open' " (on Linux); " 'open' " (on Mac OS)"
Specifies the program used to open associated files.
.TP
.IR config.commands.open.fields = ['file',\ 'url']
Specifies the names of the data fields which are to be checked for openable
URLs.
.TP
.IR config.commands.search.context = 1
Specifies the default number of context lines to provide for each search query
match.
.TP
.IR config.commands.search.grep = 'grep'
Specifies the program used to search in associated files.
.TP
.IR config.commands.search.grep_args = []
Allows the specification of additional arguments for the \fIgrep\fR command.
.TP
.IR config.commands.search.ignore_case = False
This boolean setting indicates whether search defaults to be case-insensitive.
.TP
.IR config.commands.search.decode_unicode = False
Specifies whether searches should decode all Unicode characters.
.TP
.IR config.commands.search.decode_latex = False
Specifies whether searches should decode all LaTeX sequences.
.TP
.IR config.commands.search.fuzziness = 0
Specifies the amount of fuzzy errors to allow for searches. Using this feature
requires the optional \fIregex\fR dependency to be installed.
.TP
.IR config.commands.search.skip_files = False
Specifies whether searches should skip looking through associated files.
.TP
.IR config.commands.search.skip_notes = False
Specifies whether searches should skip looking through associated notes.
.TP
.IR config.commands.show.encode_latex = True
This boolean setting indicates whether non-ASCII characters should be encoded
using LaTeX sequences during rendering via the \fIshow\fR command.
.PP
.BR DATABASE
.TP
.IR config.database.file = '~/.local/share/cobib/literature.yaml'
This setting sets the path to the database file. You can use \fI~\fR to
represent your \fI$HOME\fR directory.
.TP
.IR config.database.cache = '~/.cache/cobib/databases/'
This settings sets the path to the folder in which already parsed databases
should be stored. Set this to \fINone\fR if you want to disable caching
entirely.
.TP
.IR config.database.git = False
This boolean field indicates whether the database file should automatically be
tracked in a git repository.
Note, that you must initialize the git-tracking with \fIcobib init --git\fR. If
you already have an existing database file, it will be preserved. Nonetheless,
it is a good idea to make a backup before doing so, just in case.
Also be sure to at least set a \fIname\fR and \fIemail\fR in the git config!
.TP
.IR config.database.format.author_format = AuthorFormat.YAML
This field specifies in which format to store the \fIauthor\fR information of
each entries. See the detailed online documentation of the \fiAuthorFormat\fR
enum for all possible values. As of version 4.3.0 this defaults to a YAML format
in which each author information is stored in detailed form by splitting out the
first and last names as well as name pre- and suffixes.
.TP
.IR config.database.format.label_default = '{unidecode(label)}'
This field specifies the default label format in an f-string modification style
as interpreted by the \fImodify\fR command. The default configuration value
passes the originally provided label through \fItext-unidecode\fR which replaces
all Unicode symbols with pure ASCII ones. A more useful example is
\fI'{unidecode(author[0].last)}{year}'\fR which takes the surname of the first
author, replaces the Unicode characters and then immediately appends the
publication year.
.TP
.IR config.database.format.label_suffix = ('_',\ LabelSuffix.ALPHA)
This field specifies the default label disambiguator. The option takes a tuple
of length 2, where the first entry is the string separating the proposed label
from the disambiguator and the second one is one of the enumerators provided by
\ficonfig.LabelSuffix\fR.
.TP
.IR config.database.format.suppress_latex_warnings = True
This boolean field indicates whether latex warnings will be ignored during the
escaping of special characters.
.TP
.IR config.database.format.verbatim_fields = ['file',\ 'url']
Specifies the names of the data fields which are kept verbatim and, thus remain
unaffected from any special character conversions (e.g. LaTeX encoding).
.TP
Some fields are internally stored as lists. Upon conversion to the BibTeX
format, these need to be converted to a basic string. In this process the
entries of the list will be joined using the separators configured by the
following settings.
.TP
.IR config.database.stringify.list_separator.file = ',\ '
.TP
.IR config.database.stringify.list_separator.tags = ',\ '
.TP
.IR config.database.stringify.list_separator.url = ',\ '
.PP
.BR PARSERS
.TP
.IR config.parsers.bibtex.ignore_non_standard_types = False
This boolean setting indicates whether non-standard BibLaTex entry types should
be ignored or not.
.TP
.IR config.parsers.yaml.use_c_lib_yaml = True
This boolean setting indicates whether to use the C-based implementation of the
YAML parser. For this to work, additional packages may need to be installed.
Read https://yaml.readthedocs.io/en/latest/install.html#optional-requirements
for more details.
.PP
.BR THEME
.TP
.IR config.theme.theme = "textual-dark"
This setting allows you to specify the \fITheme\fR of the entire TUI.
Since this is tightly coupled to textual's documentation, the explanation of
this setting is best viewed online:
https://cobib.gitlab.io/cobib/cobib/config/config.html#ThemeConfig.theme
.TP
.IR config.theme.search.label = 'blue'
Specifies the color used to highlight the entry labels when displaying search
rsults.
.TP
.IR config.theme.search.label = 'red'
Specifies the color used to highlight the query matches when displaying search
results.
.TP
.IR config.theme.syntax.theme = None
Specifies the pygments scheme to use for \fIrich.Syntax\fR displays.