1rpkg(1)                          rpm-packager                          rpkg(1)
2
3
4

NAME

6       rpkg - RPM packaging utility
7

SYNOPSIS

9       rpkg [ global_options ] command [ command_options ] [ command_arguments
10       ]
11       rpkg help
12       rpkg command --help
13

DESCRIPTION

15       rpkg is a script to manage spec enriched Git repositories - meaning any
16       repositories  which  contain  an  rpm spec file. It is designed to work
17       with expanded application sources as well as with standard DistGit tar‐
18       balls  and patches. Note that you should trust the .spec files you work
19       with because many operations (like `rpkg srpm` or `rpkg lint`)  involve
20       parsing  the  spec  file, which brings along evaluation of any shell or
21       lua scriplets present in it.
22
23   Global Options
24         --config CONFIG, -C CONFIG
25                               Specify a config file to use.
26         --module-name MODULE_NAME
27                               Override the module name. Otherwise it is  dis‐
28       covered
29                               from: Git push URL or Git URL.
30         --user USER           Override the discovered user name.
31         --path  PATH            Define  the directory to work in (defaults to
32       cwd).
33         --verbose, -v         Run with verbose debug output.
34         --debug, -d           Run with debug output.
35         -q                    Run quietly only displaying errors.
36

COMMAND OVERVIEW

38       rpkg build [-h] [--config CONFIG] [-w] [--outdir OUTDIR] [--spec  SPEC]
39       [project]
40              Alias for copr-build
41
42       rpkg  ci  [-h] [-m MESSAGE] [--with-changelog] [-t] [-F FILE] [-p] [-s]
43       [files [files ...]]
44              Alias for commit
45
46       rpkg clean [-h] [--dry-run] [-x]
47              Remove untracked files
48
49       rpkg clog [-h] [--raw] [--outdir OUTDIR] [--spec SPEC]
50              Make a clog file containing top changelog entry
51
52       rpkg clone [-h] [--branches] [--branch BRANCH]  [--anonymous]  [--depth
53       DEPTH] repo [clone_target]
54              Clone and checkout a repository
55
56       rpkg  co  [-h]  [--branches]  [--branch  BRANCH] [--anonymous] [--depth
57       DEPTH] repo [clone_target]
58              Alias for clone
59
60       rpkg commit [-h] [-m MESSAGE] [--with-changelog] [-t]  [-F  FILE]  [-p]
61       [-s] [files [files ...]]
62              Commit changes
63
64       rpkg  compile [-h] [--target TARGET] [--with OPTION] [--without OPTION]
65       [--short-circuit] [--nocheck] [--outdir OUTDIR] [--spec SPEC]
66              Local test rpmbuild compile
67
68       rpkg copr-build [-h] [--config CONFIG] [-w] [--outdir  OUTDIR]  [--spec
69       SPEC] [project]
70              Build package in Copr Build System
71
72       rpkg diff [-h] [--cached] [files [files ...]]
73              Show changes between commits, commit and working tree, etc
74
75       rpkg gimmespec [-h]
76              Print the spec file name
77
78       rpkg help [-h]
79              Show usage
80
81       rpkg import [-h] [--skip-diffs] [--offline] srpm
82              Import srpm content into a module
83
84       rpkg  install [-h] [--target TARGET] [--with OPTION] [--without OPTION]
85       [--short-circuit] [--nocheck] [--outdir OUTDIR] [--spec SPEC]
86              Local test rpmbuild install
87
88       rpkg is-packed [-h] [--outdir OUTDIR] [--spec SPEC]
89              Deprecated. Tell user whether content is packed
90
91       rpkg lint [-h] [--info] [--rpmlintconf RPMLINTCONF] [--outdir OUTDIR]
92              Run rpmlint against local spec and build output if present.
93
94       rpkg local [-h] [--target TARGET] [--with  OPTION]  [--without  OPTION]
95       [--outdir OUTDIR] [--spec SPEC]
96              Local test rpmbuild binary
97
98       rpkg make-source [-h] [--outdir OUTDIR] [--spec SPEC]
99              Deprecated. Create Source0 from the content of the current work‐
100              ing directory after downloading any external sources.  The  con‐
101              tent must be of unpacked type.
102
103       rpkg new [-h]
104              Diff against last tag
105
106       rpkg new-sources [-h] files [files ...]
107              Upload source files
108
109       rpkg  prep  [-h]  [--target  TARGET] [--with OPTION] [--without OPTION]
110       [--outdir OUTDIR] [--spec SPEC]
111              Local test rpmbuild prep
112
113       rpkg pull [-h] [--rebase] [--no-rebase]
114              Pull changes from the remote repository and update  the  working
115              copy.
116
117       rpkg push [-h] [--force]
118              Push changes and annotated tags to remote repository.
119
120       rpkg sources [-h] [--outdir OUTDIR]
121              Download source files
122
123       rpkg spec [-h] [--sources] [--outdir OUTDIR] [--spec SPEC]
124              Generate spec file from a spec template
125
126       rpkg  srpm  [-h]  [--target  TARGET] [--with OPTION] [--without OPTION]
127       [--outdir OUTDIR] [--spec SPEC]
128              Create a source rpm
129
130       rpkg switch-branch [-h] [-l] [--fetch] [branch]
131              Work with branches
132
133       rpkg tag [-h] [-l] [-d] [-s] [--outdir OUTDIR] [--spec SPEC] [tag]
134              Management of git tags
135
136       rpkg unused-patches [-h] [--outdir OUTDIR] [--spec SPEC]
137              Print list of patches not referenced by name in the specfile
138
139       rpkg upload [-h] files [files ...]
140              Upload source files
141
142       rpkg verify-files [-h] [--outdir OUTDIR]
143              Locally verify %%files section
144
145       rpkg verrel [-h] [--outdir OUTDIR] [--spec SPEC]
146              Print the name-version-release
147

COMMAND REFERENCE

149   rpkg build
150         usage: rpkg build  [-h]  [--config  CONFIG]  [-w]  [--outdir  OUTDIR]
151       [--spec SPEC]
152                           [project]
153
154         Build  package  in  Copr  Build  System.  You  need  to have copr-cli
155       installed and
156         also set up Copr api key. For more information about the api key, see
157       API KEY
158         section in copr-cli(1) man page.
159
160         positional arguments:
161           project           Name  of  the project in format OWNER/PROJECT. If
162       not
163                            specified, project will be set to module name.
164
165         optional arguments:
166           -h, --help       show this help message and exit
167           --config CONFIG  Path to an alternative Copr configuration file
168           -w, --wait       Wait for build to finish.
169           --outdir OUTDIR  Where to put any generated rpm content.  Directory
170       must
171                            exist.
172           --spec  SPEC       An  input  spec template. If not given, the spec
173       template is
174                            auto-located  in  path  as  a  file  ending   with
175       ".spec.rpkg" or
176                            ".spec" suffix in this order.
177
178
179   rpkg ci
180         usage:  rpkg  ci  [-h] [-m MESSAGE] [--with-changelog] [-t] [-F FILE]
181       [-p] [-s]
182                        [files [files ...]]
183
184         Alias for commit.
185
186         positional arguments:
187           files                 Optional list of specific files to commit
188
189         optional arguments:
190           -h, --help            show this help message and exit
191           -m MESSAGE, --message MESSAGE
192                                 Use the given <msg>  as  the  commit  message
193       summary
194           --with-changelog       Get  the  last changelog from SPEC as commit
195       message
196                                 content. This option must  be  used  with  -m
197       together.
198           -t, --tag             Create a tag for this commit
199           -F FILE, --file FILE  Take the commit message from the given file
200           -p, --push            Commit and push as one action
201           -s, --signoff         Include a signed-off-by
202
203
204   rpkg clean
205         usage: rpkg clean [-h] [--dry-run] [-x]
206
207         This  command  can  be  used  to  clean up your working directory. By
208       default it
209         will follow .gitignore rules.
210
211         optional arguments:
212           -h, --help     show this help message and exit
213           --dry-run, -n  Perform a dry-run
214           -x             Do not follow .gitignore rules
215
216
217   rpkg clog
218         usage: rpkg clog [-h] [--raw] [--outdir OUTDIR] [--spec SPEC]
219
220         This will create a file named "clog" that  contains  the  latest  rpm
221       changelog
222         entry. The leading "- " text will be stripped.
223
224         optional arguments:
225           -h, --help       show this help message and exit
226           --raw             Generate  a more "raw" clog without twiddling the
227       contents
228           --outdir OUTDIR  Where to put any generated rpm content.  Directory
229       must
230                            exist.
231           --spec  SPEC       An  input  spec template. If not given, the spec
232       template is
233                            auto-located  in  path  as  a  file  ending   with
234       ".spec.rpkg" or
235                            ".spec" suffix in this order.
236
237
238   rpkg clone
239         usage: rpkg clone [-h] [--branches] [--branch BRANCH] [--anonymous]
240                           [--depth DEPTH]
241                           repo [clone_target]
242
243         This  command  will  clone  the  named repository from the configured
244       repository
245         base URL. By default it will also checkout the master branch for your
246       working
247         copy.
248
249         positional arguments:
250           repo                  Name of the repository to clone
251           clone_target          Directory in which to clone the repository
252
253         optional arguments:
254           -h, --help            show this help message and exit
255           --branches,  -B         Do  an  old style checkout with subdirs for
256       branches
257           --branch BRANCH, -b BRANCH
258                                 Check out a specific branch
259           --anonymous, -a       Check out a module anonymously
260           --depth DEPTH         Create a shallow clone with a  history  trun‐
261       cated to the
262                                 specified number of commits
263
264
265   rpkg co
266         usage: rpkg co [-h] [--branches] [--branch BRANCH] [--anonymous]
267                        [--depth DEPTH]
268                        repo [clone_target]
269
270         Alias for clone.
271
272         positional arguments:
273           repo                  Name of the repository to clone
274           clone_target          Directory in which to clone the repository
275
276         optional arguments:
277           -h, --help            show this help message and exit
278           --branches,  -B         Do  an  old style checkout with subdirs for
279       branches
280           --branch BRANCH, -b BRANCH
281                                 Check out a specific branch
282           --anonymous, -a       Check out a module anonymously
283           --depth DEPTH         Create a shallow clone with a  history  trun‐
284       cated to the
285                                 specified number of commits
286
287
288   rpkg commit
289         usage:  rpkg  commit  [-h]  [-m  MESSAGE] [--with-changelog] [-t] [-F
290       FILE] [-p]
291                            [-s]
292                            [files [files ...]]
293
294         This invokes a git commit. All tracked files  with  changes  will  be
295       committed
296         unless a specific file list is provided. $EDITOR will be used to gen‐
297       erate a
298         changelog message unless one is given to the command. A tag  or  push
299       can be
300         done at the same time.
301
302         positional arguments:
303           files                 Optional list of specific files to commit
304
305         optional arguments:
306           -h, --help            show this help message and exit
307           -m MESSAGE, --message MESSAGE
308                                 Use  the  given  <msg>  as the commit message
309       summary
310           --with-changelog      Get the last changelog from  SPEC  as  commit
311       message
312                                 content.  This  option  must  be used with -m
313       together.
314           -t, --tag             Create a tag for this commit
315           -F FILE, --file FILE  Take the commit message from the given file
316           -p, --push            Commit and push as one action
317           -s, --signoff         Include a signed-off-by
318
319
320   rpkg compile
321         usage: rpkg compile [-h] [--target TARGET] [--with OPTION] [--without
322       OPTION]
323                             [--short-circuit] [--nocheck] [--outdir OUTDIR]
324                             [--spec SPEC]
325
326         This  command  calls  rpmbuild  to compile the source. By default the
327       prep and
328         configure stages will be  done  as  well,  unless  the  short-circuit
329       option is
330         used.
331
332         optional arguments:
333           -h, --help        show this help message and exit
334           --target TARGET   Prep for a specific arch or arch-vendor-os.
335           --with  OPTION     Enable %bcond spec OPTION. Can be specified mul‐
336       tiple
337                             times.
338           --without OPTION  Disable %bcond spec OPTION. Can be specified mul‐
339       tiple
340                             times.
341           --short-circuit   short-circuit compile
342           --nocheck         nocheck compile
343           --outdir OUTDIR   Where to put any generated rpm content. Directory
344       must
345                             exist.
346           --spec SPEC       An input spec template. If not  given,  the  spec
347       template is
348                             auto-located  in  path  as  a  file  ending  with
349       ".spec.rpkg" or
350                             ".spec" suffix in this order.
351
352
353   rpkg copr-build
354         usage: rpkg copr-build [-h] [--config CONFIG] [-w] [--outdir OUTDIR]
355                                [--spec SPEC]
356                                [project]
357
358         Build package in  Copr  Build  System.  You  need  to  have  copr-cli
359       installed and
360         also set up Copr api key. For more information about the api key, see
361       API KEY
362         section in copr-cli(1) man page.
363
364         positional arguments:
365           project          Name of the project in  format  OWNER/PROJECT.  If
366       not
367                            specified, project will be set to module name.
368
369         optional arguments:
370           -h, --help       show this help message and exit
371           --config CONFIG  Path to an alternative Copr configuration file
372           -w, --wait       Wait for build to finish.
373           --outdir  OUTDIR  Where to put any generated rpm content. Directory
374       must
375                            exist.
376           --spec SPEC      An input spec template. If  not  given,  the  spec
377       template is
378                            auto-located   in  path  as  a  file  ending  with
379       ".spec.rpkg" or
380                            ".spec" suffix in this order.
381
382
383   rpkg diff
384         usage: rpkg diff [-h] [--cached] [files [files ...]]
385
386         Use git diff to show changes that have been made to tracked files. By
387       default
388         cached changes (changes that have been git added) will not be shown.
389
390         positional arguments:
391           files       Optionally diff specific files
392
393         optional arguments:
394           -h, --help  show this help message and exit
395           --cached    View staged changes
396
397
398   rpkg gimmespec
399         usage: rpkg gimmespec [-h]
400
401         Print the spec file name.
402
403         optional arguments:
404           -h, --help  show this help message and exit
405
406
407   rpkg help
408         usage: rpkg help [-h]
409
410         Show usage.
411
412         optional arguments:
413           -h, --help  show this help message and exit
414
415
416   rpkg import
417         usage: rpkg import [-h] [--skip-diffs] [--offline] srpm
418
419         This  will  extract  sources, patches, and the spec file from an srpm
420       and update
421         the current module accordingly. It will import to the current  branch
422       by
423         default.
424
425         positional arguments:
426           srpm          Source rpm to import
427
428         optional arguments:
429           -h, --help    show this help message and exit
430           --skip-diffs  Don't show diffs when import srpms
431           --offline     Do not upload files into lookaside cache
432
433
434   rpkg install
435         usage: rpkg install [-h] [--target TARGET] [--with OPTION] [--without
436       OPTION]
437                             [--short-circuit] [--nocheck] [--outdir OUTDIR]
438                             [--spec SPEC]
439
440         This will call rpmbuild to run the install section. All leading  sec‐
441       tions will
442         be processed as well, unless the short-circuit option is used.
443
444         optional arguments:
445           -h, --help        show this help message and exit
446           --target TARGET   Prep for a specific arch or arch-vendor-os.
447           --with  OPTION     Enable %bcond spec OPTION. Can be specified mul‐
448       tiple
449                             times.
450           --without OPTION  Disable %bcond spec OPTION. Can be specified mul‐
451       tiple
452                             times.
453           --short-circuit   short-circuit install
454           --nocheck         nocheck install
455           --outdir OUTDIR   Where to put any generated rpm content. Directory
456       must
457                             exist.
458           --spec SPEC       An input spec template. If not  given,  the  spec
459       template is
460                             auto-located  in  path  as  a  file  ending  with
461       ".spec.rpkg" or
462                             ".spec" suffix in this order.
463
464
465   rpkg is-packed
466         usage: rpkg is-packed [-h] [--outdir OUTDIR] [--spec SPEC]
467
468         Deprecated. Determine whether the  package  content  in  the  working
469       directory is
470         packed or unpacked and print that information to the screen.
471
472         optional arguments:
473           -h, --help       show this help message and exit
474           --outdir  OUTDIR  Where to put any generated rpm content. Directory
475       must
476                            exist.
477           --spec SPEC      An input spec template. If  not  given,  the  spec
478       template is
479                            auto-located   in  path  as  a  file  ending  with
480       ".spec.rpkg" or
481                            ".spec" suffix in this order.
482
483
484   rpkg lint
485         usage: rpkg lint [-h] [--info] [--rpmlintconf RPMLINTCONF]  [--outdir
486       OUTDIR]
487
488         Rpmlint  can  be  configured  using the --rpmlintconf/-r option or by
489       setting a
490         .rpmlint file in the working directory.
491
492         optional arguments:
493           -h, --help            show this help message and exit
494           --info, -i            Display explanations for reported messages
495           --rpmlintconf RPMLINTCONF, -r RPMLINTCONF
496                                 Use a specific configuration file for rpmlint
497           --outdir OUTDIR       Directory with rpm items to be linted or just
498       a single
499                                 rpm item like a .spec file. If not specified,
500       a
501                                 directory  from  base  output  path  will  be
502       selected.
503
504
505   rpkg local
506         usage:  rpkg  local [-h] [--target TARGET] [--with OPTION] [--without
507       OPTION]
508                           [--outdir OUTDIR] [--spec SPEC]
509
510         Locally test run of rpmbuild producing binary RPMs. The rpmbuild out‐
511       put will
512         be logged into a file named .build-%{version}-%{release}.log
513
514         optional arguments:
515           -h, --help        show this help message and exit
516           --target TARGET   Prep for a specific arch or arch-vendor-os.
517           --with  OPTION     Enable %bcond spec OPTION. Can be specified mul‐
518       tiple
519                             times.
520           --without OPTION  Disable %bcond spec OPTION. Can be specified mul‐
521       tiple
522                             times.
523           --outdir OUTDIR   Where to put any generated rpm content. Directory
524       must
525                             exist.
526           --spec SPEC       An input spec template. If not  given,  the  spec
527       template is
528                             auto-located  in  path  as  a  file  ending  with
529       ".spec.rpkg" or
530                             ".spec" suffix in this order.
531
532
533   rpkg make-source
534         usage: rpkg make-source [-h] [--outdir OUTDIR] [--spec SPEC]
535
536         Deprecated. Puts content of the  current  working  directory  into  a
537       gzip-
538         compressed  archive  named according to Source0 filename as specified
539       in the
540         .spec file. The content must be of unpacked type, otherwise no action
541       is
542         taken.  Unpacked  content  is such that it contains a .spec file that
543       references
544         no present source or patch (typically it contains only Source0  being
545       generated
546         automatically)  and  there  is  at  least one file not in the list of
547       ignored
548         content (README,  README.md,  sources,  LICENSE,  tito.props,  hidden
549       files, .spec
550         file).  Note  that  by  invoking  this  command with --outdir ./, the
551       directory
552         content becomes "packed".
553
554         optional arguments:
555           -h, --help       show this help message and exit
556           --outdir OUTDIR  Where to put any generated rpm content.  Directory
557       must
558                            exist.
559           --spec  SPEC       An  input  spec template. If not given, the spec
560       template is
561                            auto-located  in  path  as  a  file  ending   with
562       ".spec.rpkg" or
563                            ".spec" suffix in this order.
564
565
566   rpkg new
567         usage: rpkg new [-h]
568
569         This will use git to show a diff of all the changes (even uncommitted
570       changes)
571         since the last git tag was applied.
572
573         optional arguments:
574           -h, --help  show this help message and exit
575
576
577   rpkg new-sources
578         usage: rpkg new-sources [-h] files [files ...]
579
580         This will upload new source file(s) to lookaside cache, and all  file
581       names
582         listed  in  sources  file  will  be replaced. .gitignore will be also
583       updated with
584         new uploaded file(s). Please remember to commit them.
585
586         positional arguments:
587           files
588
589         optional arguments:
590           -h, --help  show this help message and exit
591
592
593   rpkg prep
594         usage: rpkg prep [-h] [--target TARGET]  [--with  OPTION]  [--without
595       OPTION]
596                          [--outdir OUTDIR] [--spec SPEC]
597
598         Use  rpmbuild to "prep" the sources (unpack the source archive(s) and
599       apply any
600         patches.)
601
602         optional arguments:
603           -h, --help        show this help message and exit
604           --target TARGET   Prep for a specific arch or arch-vendor-os.
605           --with OPTION     Enable %bcond spec OPTION. Can be specified  mul‐
606       tiple
607                             times.
608           --without OPTION  Disable %bcond spec OPTION. Can be specified mul‐
609       tiple
610                             times.
611           --outdir OUTDIR   Where to put any generated rpm content. Directory
612       must
613                             exist.
614           --spec  SPEC        An  input spec template. If not given, the spec
615       template is
616                             auto-located  in  path  as  a  file  ending  with
617       ".spec.rpkg" or
618                             ".spec" suffix in this order.
619
620
621   rpkg pull
622         usage: rpkg pull [-h] [--rebase] [--no-rebase]
623
624         This  command  uses git to fetch remote changes and apply them to the
625       current
626         working copy. A rebase option is available which can be used to avoid
627       merges.
628
629         optional arguments:
630           -h, --help   show this help message and exit
631           --rebase      Rebase  the  locally  committed changes on top of the
632       remote
633                        changes after fetching. This can avoid a merge commit,
634       but does
635                        rewrite local history.
636           --no-rebase   Do  not  rebase, overriding .git settings to the con‐
637       trary
638
639         See git pull --help for more details
640
641
642   rpkg push
643         usage: rpkg push [-h] [--force]
644
645         Push changes and annotated tags to remote repository.
646
647         optional arguments:
648           -h, --help   show this help message and exit
649           --force, -f  Force push
650
651
652   rpkg sources
653         usage: rpkg sources [-h] [--outdir OUTDIR]
654
655         Download source files
656
657         optional arguments:
658           -h, --help       show this help message and exit
659           --outdir OUTDIR  Directory to download files into (defaults to pwd)
660
661
662   rpkg spec
663         usage: rpkg spec [-h] [--sources] [--outdir OUTDIR] [--spec SPEC]
664
665         Preprocess a given spec template and put the resulting spec file into
666       outdir.
667         The  spec  template  is simply copied into the outdir if spec prepro‐
668       cessing is
669         turned off or if the input spec template does not  contain  any  pre‐
670       processor
671         macros.
672
673         optional arguments:
674           -h, --help       show this help message and exit
675           --sources         Enable  source  generation by the input spec tem‐
676       plate. By
677                            default disabled.
678           --outdir OUTDIR  Where to put any generated rpm content.  Directory
679       must
680                            exist.
681           --spec  SPEC       An  input  spec template. If not given, the spec
682       template is
683                            auto-located  in  path  as  a  file  ending   with
684       ".spec.rpkg" or
685                            ".spec" suffix in this order.
686
687
688   rpkg srpm
689         usage:  rpkg  srpm  [-h] [--target TARGET] [--with OPTION] [--without
690       OPTION]
691                          [--outdir OUTDIR] [--spec SPEC]
692
693         Create a source rpm
694
695         optional arguments:
696           -h, --help        show this help message and exit
697           --target TARGET   Prep for a specific arch or arch-vendor-os.
698           --with OPTION     Enable %bcond spec OPTION. Can be specified  mul‐
699       tiple
700                             times.
701           --without OPTION  Disable %bcond spec OPTION. Can be specified mul‐
702       tiple
703                             times.
704           --outdir OUTDIR   Where to put any generated rpm content. Directory
705       must
706                             exist.
707           --spec  SPEC        An  input spec template. If not given, the spec
708       template is
709                             auto-located  in  path  as  a  file  ending  with
710       ".spec.rpkg" or
711                             ".spec" suffix in this order.
712
713
714   rpkg switch-branch
715         usage: rpkg switch-branch [-h] [-l] [--fetch] [branch]
716
717         This  command  can  switch  to a local git branch. If provided with a
718       remote
719         branch name that does not have a local match it will create  one.  It
720       can also
721         be used to list the existing local and remote branches.
722
723         positional arguments:
724           branch      Branch name to switch to
725
726         optional arguments:
727           -h, --help  show this help message and exit
728           -l, --list  List both remote-tracking branches and local branches
729           --fetch     Fetch new data from remote before switch
730
731
732   rpkg tag
733         usage:  rpkg  tag [-h] [-l] [-d] [-s] [--outdir OUTDIR] [--spec SPEC]
734       [tag]
735
736         This command uses git to create, list, or delete tags.
737
738         positional arguments:
739           tag              Name of the tag
740
741         optional arguments:
742           -h, --help       show this help message and exit
743           -l, --list       List all tags with a given pattern, or all if  not
744       pattern
745                            is given
746           -d, --delete     Delete a tag
747           -s, --skip-edit  Skips changelog editing when creating a tag.
748           --outdir  OUTDIR  Where to put any generated rpm content. Directory
749       must
750                            exist.
751           --spec SPEC      An input spec template. If  not  given,  the  spec
752       template is
753                            auto-located   in  path  as  a  file  ending  with
754       ".spec.rpkg" or
755                            ".spec" suffix in this order.
756
757
758   rpkg unused-patches
759         usage: rpkg unused-patches [-h] [--outdir OUTDIR] [--spec SPEC]
760
761         Print list of patches not referenced by name in the specfile.
762
763         optional arguments:
764           -h, --help       show this help message and exit
765           --outdir OUTDIR  Where to put any generated rpm content.  Directory
766       must
767                            exist.
768           --spec  SPEC       An  input  spec template. If not given, the spec
769       template is
770                            auto-located  in  path  as  a  file  ending   with
771       ".spec.rpkg" or
772                            ".spec" suffix in this order.
773
774
775   rpkg upload
776         usage: rpkg upload [-h] files [files ...]
777
778         This  command  will  upload  new  source  file(s) to lookaside cache.
779       Source file
780         names are appended to sources  file,  and  .gitignore  will  be  also
781       updated with
782         new uploaded file(s). Please remember to commit them.
783
784         positional arguments:
785           files
786
787         optional arguments:
788           -h, --help  show this help message and exit
789
790
791   rpkg verify-files
792         usage: rpkg verify-files [-h] [--outdir OUTDIR]
793
794         Locally run 'rpmbuild -bl' to verify the spec file's %files sections.
795       This
796         requires a successful run of 'rpkg install' in advance.
797
798         optional arguments:
799           -h, --help       show this help message and exit
800           --outdir OUTDIR  Output directory with build results.
801
802
803   rpkg verrel
804         usage: rpkg verrel [-h] [--outdir OUTDIR] [--spec SPEC]
805
806         Print the name-version-release.
807
808         optional arguments:
809           -h, --help       show this help message and exit
810           --outdir OUTDIR  Where to put any generated rpm content.  Directory
811       must
812                            exist.
813           --spec  SPEC       An  input  spec template. If not given, the spec
814       template is
815                            auto-located  in  path  as  a  file  ending   with
816       ".spec.rpkg" or
817                            ".spec" suffix in this order.
818
819

CONFIGURATION

821       rpkg  reads  configuration  options  from  the  following files in this
822       order:
823
824           /etc/rpkg.conf,      ~/.config/rpkg.conf,      <gitroot>/rpkg.conf,
825       ./rpkg.conf
826
827       Configuration found in ./rpkg.conf has the highest priority. Configura‐
828       tion in /etc/rpkg.conf has the lowest priority.  <gitroot>  placeholder
829       above  means  the top level of the Git repository we are working in. If
830       we are in a plain directory and all our  parent  directories  are  also
831       plain, reading of <gitroot>/rpkg.conf is simply skipped.
832
833
834   DEFAULT COMMENTED CONFIGURATION
835           [rpkg]
836           # whether to enable spec preprocessing,
837           # that is parsing and evaluation of {{{ ... }}} expressions
838           preprocess_spec = True
839
840           # generate tarball from sources named
841           # according to Source0 definition in
842           # a spec file. Used by `rpkg srpm`.
843           # Deprecated by spec templates.
844           auto_pack = False
845
846           # base directory where results should be stored
847           base_output_path = /tmp/rpkg
848
849           # sets permanent value for --module-name option
850           # for each executed rpkg command
851           # module_name = @group/project
852
853           [git]
854           #  download URL for DistGit lookaside cache, used by `rpkg sources`
855       command
856           # %(ns1)s, %(pkg)s are parts of a module name (e.g. rpms/rpkg-util)
857           # %(filename)s, %(hashtype)s,  %(hash)s,  %(filename)s  fields  are
858       read from 'sources' file if present
859           lookaside                  =                 https://src.fedorapro
860       ject.org/repo/pkgs/%(ns1)s/%(pkg)s/%(file‐
861       name)s/%(hashtype)s/%(hash)s/%(filename)s
862
863           # upload URL for DistGit lookaside cache, used by `rpkg upload`
864           lookaside_cgi = https://src.fedoraproject.org/repo/pkgs/upload.cgi
865
866           # default Git repository URL, used by `rpkg clone <module>`
867           gitbaseurl = ssh://%(user)s@pkgs.fedoraproject.org/%(module)s
868
869           #  default  anonymous  Git  repository  URL, used by `rpkg clone -a
870       <module>`
871           anongiturl = https://src.fedoraproject.org/%(module)s
872
873

EXAMPLES

875       Run %prep phase of an rpm build:
876
877           $ rpkg prep
878           git_pack: packing directory /home/clime/rpkg-util
879           git_pack:        Wrote:        /tmp/rpkg/rpkg-util-1-j8x35rb3/rpkg-
880       util-2.2.git.18.5b6a884.tar.gz
881           Wrote: /tmp/rpkg/rpkg-util-1-j8x35rb3/rpkg-util.spec
882           Executing(%prep): /bin/sh -e /var/tmp/rpm-tmp.vE42SH
883           + umask 022
884           + cd /tmp/rpkg/rpkg-util-1-j8x35rb3
885           + cd /tmp/rpkg/rpkg-util-1-j8x35rb3
886           + rm -rf rpkg-util-2.2.git.18.5b6a884
887           +     /usr/bin/gzip     -dc    /tmp/rpkg/rpkg-util-1-j8x35rb3/rpkg-
888       util-2.2.git.18.5b6a884.tar.gz
889           + /usr/bin/tar -xof -
890           + STATUS=0
891           + '[' 0 -ne 0 ']'
892           + cd rpkg-util-2.2.git.18.5b6a884
893           + /usr/bin/chmod -Rf a+rX,u+w,g-w,o-w .
894           + exit 0
895
896       For the following command, you need to have a project in COPR  created.
897       See quick tutorial at
898
899       https://docs.pagure.org/copr.copr/user_documentation.html#quick-start
900
901       on how to do it.
902
903           $ rpkg build
904           git_pack: packing directory /home/clime/rpkg-util
905           git_pack:        Wrote:        /tmp/rpkg/rpkg-util-2-ab6awb8y/rpkg-
906       util-2.2.git.18.0cb6974.tar.gz
907           Wrote: /tmp/rpkg/rpkg-util-2-ab6awb8y/rpkg-util.spec
908           Wrote:                         /tmp/rpkg/rpkg-util-2-ab6awb8y/rpkg-
909       util-2.2.git.18.0cb6974-1.fc28.src.rpm
910           Uploading        package       /tmp/rpkg/rpkg-util-2-ab6awb8y/rpkg-
911       util-2.2.git.18.0cb6974-1.fc28.src.rpm
912           100% |################################| 122kB 359kB/s eta 0:00:00
913           Build was added to rpkg-util:
914             https://copr.fedorainfracloud.org/coprs/build/782327/
915           Created builds: 782327
916
917       Here you can see a simple operation of generation spec file from a tem‐
918       plate:
919
920           $ rpkg spec
921           Wrote: /tmp/rpkg/rpkg-util-3-1u34plfx/rpkg-util.spec
922
923

SPEC TEMPLATES

925       Apart from being useful as a means to handle unpacked as well as packed
926       content, they also make it possible to generate certain parts  of  your
927       spec  file  automatically from a Git repository where your spec file is
928       located. You need to have "spec_preprocess" configuration option set to
929       True in rpkg config to use this functionality.
930
931
932   BASIC EXAMPLE
933           Name:       {{{ git_name }}}
934           Version:    {{{ git_version }}}
935           Release:    1%{?dist}
936           Summary:    This is a test package.
937
938           License:    GPLv2+
939           URL:        https://someurl.org
940           VCS:        {{{ git_vcs }}}
941
942           Source:     {{{ git_pack }}}
943
944           %description
945           This is a test package.
946
947           %prep
948           {{{ git_setup_macro }}}
949
950           %changelog
951           {{{ git_changelog }}}
952
953       Having  a  spec  template  like this in your project (instead of just a
954       plain spec file) allows you to build source and rpm packages  automati‐
955       cally following git history of your project.
956
957
958   MACRO REFERENCE
959       BASE GIT MACROS
960
961              Without  any  parameters,  these macros work on repository level
962              and use globally available repository information.
963
964              NOTE: If your local repository is not  properly  initialized  or
965              if,  for example, the .git metadata directory in your local tree
966              has been renamed or removed, operation of the  base  macros  can
967              get  out  of  the intended scope. It is therefore recommended to
968              use more specific git_dir_* macros  where  possible,  which  are
969              always  bound  to  the  directory  where  the input spec file is
970              located. This is mainly relevant for  git_pack  and  git_archive
971              macros (see below).
972
973              Output  of  every  git macro call is cached and other macros are
974              made to take those cached values into account by  default.   You
975              can  see  that  a  macro  uses a cached value as a default input
976              parameter value by looking at its function header definition and
977              searching for the `cached` keyword.
978
979              E.g.
980
981                  git_version [name="$(cached git_name)"] [lead=0] [follow=]
982
983              Default  value  for  name in this definition is derived from the
984              cached output of the previously  invoked  `git_name`  macro.  If
985              `git_name`  macro  has  not been invoked or if its output was an
986              empty string, the default value for the `name=` parameter  above
987              will be also an empty string.
988
989              Note that $(cached_git_name_version) in the function header def‐
990              initions below is  an  alias  for  "$(cached  git_name)-$(cached
991              git_version)".
992
993              git_name [name=] [prepend=] [append=]
994
995              Without  any  parameters,  lookup  remote  URL for the currently
996              active branch and output its basename with .git suffix stripped.
997              If  the  remote URL could not be determined, use "origin" remote
998              URL instead.
999
1000                  Optional arguments:
1001                      name     the base name to be output
1002                      prepend  string to be prepended to the base name
1003                      append   string to be appended to the base name
1004
1005              git_version [name="$(cached git_name)"] [lead=0] [follow=]
1006
1007              Output version of a subpackage given by ${name}. The version  is
1008              a string constructed of the following parts:
1009
1010                  "${lead}.${follow}${commit_count_appendix}${wtree_appendix}"
1011
1012              ${lead}  is  a mandatory argument of the macro. By default it is
1013              set to zero.
1014
1015              ${follow} (if not specified) is obtained from the follow part of
1016              the latest tag made for the subpackage given by ${name}.
1017
1018              ${commit_count_appendix} is generated only if the current commit
1019              is not tagged for the given subpackage and it is composed of the
1020              following parts
1021
1022                  .git.<commit_count>.<latest_commit_short_hash>
1023
1024              Commit  count  is a number of commits from the latest tag on the
1025              given subpackage.
1026
1027              ${wtree_appendix} is generated only if the currently checked out
1028              working tree is dirty. It is composed of the following parts:
1029
1030                  .wtree.<encoded_latest_file_status_change>
1031
1032                  Optional arguments:
1033                      name     name of a subpackage
1034                      lead     major version substring
1035                      follow    minor version substring, dynamically generated
1036              if not specified
1037
1038                  Environment variables:
1039                      VERSION_BUMP: if set to a non-empty value, the following
1040              procedure is applied
1041                      to get the version string:
1042
1043                      If  $follow  is  specified  by  user  explicitly, return
1044              $lead.$follow.
1045
1046                      Otherwise, extract $follow from the latest  tag  as  the
1047              last version component (after the last dot)
1048                      and  return $lead.$follow+1. If $follow is not a number,
1049              throw an error (manual setting of follow
1050                      is needed).
1051
1052                      rpkg sets the VERSION_BUMP variable into the preprocess‐
1053              ing environment during
1054                      execution  of  `rpkg  tag`  subcommand. Otherwise, it is
1055              unset.
1056
1057              git_vcs [subtree=]
1058
1059              Output pseudo repository URL pointing the currently checked  out
1060              tree.
1061
1062              Example           output:          git+ssh://git@pagure.io/test-
1063              project.git#dadef2a8b9554e94797a7336261192e02d5d9351:
1064
1065                  Optional arguments:
1066                      subtree     path to a subtree to generate the URL for
1067
1068              git_pack     [path="$(git      rev-parse      --show-toplevel)"]
1069              [dir_name="$(cached_git_name_version)"]
1070              [source_name="$(cached_git_name_version).tar.gz"]
1071
1072              Pack the whole working tree content  (including  untracked  con‐
1073              tent)  into  a  gzipped  source tarball and output $source_name,
1074              which is a filename of the created tarball.  Uses GNU tar to  do
1075              the job. Files ignored by git as well as .git metadata directory
1076              will be excluded from the resulting tarball.
1077
1078                  Optional arguments:
1079                      path         path  to  a  specific  subdirectory  to  be
1080              packed
1081                      dir_name      top-level  directory  name  in the created
1082              tarball
1083                      source_name  filename of the created source tarball
1084
1085                  Enviroment variables:
1086                      OUTDIR:  if  empty,  git_pack  will  not  generate   any
1087              sources, only the source filename will be output
1088
1089                      rpkg sets OUTDIR, only if the tarball is actually needed
1090              to be generated. It does not set it
1091                      when `rpkg spec` is called (without any additional argu‐
1092              ments).
1093
1094              git_archive     [path="$(git     rev-parse    --show-toplevel)"]
1095              [dir_name="$(cached_git_name_version)"]
1096              [source_name="$(cached_git_name_version).tar.gz"]
1097
1098              Pack  the  latest commit tree content into a gzipped source tar‐
1099              ball and output $source_name, which is a filename of the created
1100              tarball.  Uses `git archive` to do the job. Note that this macro
1101              will refuse to generate a tarball if your working tree is dirty.
1102
1103                  Optional arguments:
1104                      path         path  to  a  specific  subdirectory  to  be
1105              packed
1106                      dir_name      top-level  directory  name  in the created
1107              tarball
1108                      source_name  filename of the created source tarball
1109
1110                  Enviroment variables:
1111                      OUTDIR: if empty,  git_archive  will  not  generate  any
1112              sources, only the source filename will be output
1113
1114                      rpkg sets OUTDIR, only if the tarball is actually needed
1115              to be generated. It does not set it
1116                      when `rpkg spec` is called (without any additional argu‐
1117              ments).
1118
1119              git_setup_macro [dir_name="$(cached_git_name_version)"]
1120
1121              Output  %setup  rpm macro for the given top-level source-tarball
1122              directory.
1123
1124                  Optional arguments:
1125                      dir_name     name of  the  top-level  directory  in  the
1126              source-tarball
1127
1128              git_changelog     [name="$(cached    git_name)"]    [since_tag=]
1129              [until_tag=] [header_locale=POSIX] [header_date_format="%a %b %d
1130              %Y"] [body_wrap=80]
1131
1132              Output rpm spec changelog as generated from tag messages for the
1133              subpackage given by ${name}.
1134
1135                  Optional arguments:
1136                      name                name of the subpackage  to  generate
1137              the changelog for
1138                      since_tag            start  the  changelog  records with
1139              this tag
1140                      until_tag           end the changelog records with  this
1141              tag
1142                      header_locale        locale  to  be  used when changelog
1143              record date is being generated
1144                      header_date_format   date  format  to  be  used  in  the
1145              changelog record headers
1146                      body_wrap            maximum  allowed  line  length  for
1147              changelog body
1148
1149              When `rpkg tag` is called, it allows you to specify a  tag  mes‐
1150              sage.  This  is  the  message  that  will be used as a changelog
1151              record body.
1152
1153
1154
1155       GIT_DIR MACROS
1156
1157              These macros operate on a directory level. In particular,  on  a
1158              directory  where  the  input spec file template is located. They
1159              are basically aliases to the GIT BASE  MACROS  with  some  input
1160              values  set  specifically for the directory-level operation. The
1161              input spec template location is given by INPUT_PATH  environment
1162              variable set by rpkg. You can influence it from the command line
1163              by explicitly specifying  --spec  <template_path>  argument  for
1164              rpkg subcommands that support it.
1165
1166              Below  you  can  see  to what the GIT DIR macros expand. In some
1167              cases, the macro is a direct alias to the  underlying  git  base
1168              macro.
1169
1170              git_dir_name
1171
1172                  git_name  append="-$(git  -C "$(dirname "$INPUT_PATH")" rev-
1173              parse --show-prefix | path_to_name_suffix)"
1174
1175                  Outputs repository origin URL  basename  appended  with  the
1176              path (after slash to dash substitution) from the repository
1177                  root to the spec file's directory.
1178
1179              git_dir_version
1180
1181                  git_version
1182
1183              git_dir_vcs
1184
1185                  git_vcs  subtree="$(git  -C  "$(dirname "$INPUT_PATH")" rev-
1186              parse --show-prefix)"
1187
1188                  Outputs VCS pseudo URL pointing to the spec file's subdirec‐
1189              tory.
1190
1191              git_dir_pack
1192
1193                  git_pack path="$(dirname "$INPUT_PATH")"
1194
1195                  Packs spec file's subdirectory by using GNU tar.
1196
1197              git_dir_archive
1198
1199                  git_archive path="$(dirname "$INPUT_PATH")"
1200
1201                  Packs spec file's subdirectory by using `git archive`.
1202
1203              git_dir_setup_macro
1204
1205                  git_setup_macro
1206
1207              git_dir_changelog
1208
1209                  git_changelog
1210
1211
1212
1213       GIT_CWD MACROS
1214
1215              These  macros  operate on a directory level. In particular, on a
1216              rpkg's working directory. Again, they are  aliases  to  the  GIT
1217              BASE  MACROS  with  some  input  values set specifically for the
1218              directory-level operation.
1219
1220              You can influence the rpkg's working dir from the  command  line
1221              by explicitly specifying its --path argument.
1222
1223              Below  you  can  see  to what the GIT_CWD macros expand. In some
1224              cases, the macro is a direct alias for the underlying  git  base
1225              macro.
1226
1227              git_cwd_name
1228
1229                  git_name  append="-$(git -C "$(pwd)" rev-parse --show-prefix
1230              | path_to_name_suffix)"
1231
1232                  Outputs repository origin URL  basename  appended  with  the
1233              rpkg's  working  directory  path  (after slash to dash substitu‐
1234              tion).
1235
1236              git_cwd_version
1237
1238                  git_version
1239
1240              git_cwd_vcs
1241
1242                  git_vcs subtree="$(git -C "$(pwd)" rev-parse --show-prefix)"
1243
1244                  Outputs VCS pseudo URL pointing to the rpkg's working direc‐
1245              tory.
1246
1247              git_cwd_pack
1248
1249                  git_pack path="$(pwd)"
1250
1251                  Packs rpkg's working directory by using GNU tar.
1252
1253              git_cwd_archive
1254
1255                  git_archive path="$(pwd)"
1256
1257                  Packs rpkg's working directory by using `git archive`.
1258
1259              git_cwd_setup_macro
1260
1261                  git_setup_macro
1262
1263              git_cwd_changelog
1264
1265                  git_changelog
1266
1267

USER-DEFINED MACROS

1269       You  can  define  your own rpkg macros that are basically just standard
1270       bash functions read from rpkg.macros file placed in an  rpkg's  working
1271       directory.  Standard  output  of your custom macro will be captured and
1272       the {{{ <macro_name> }}} invocation in  an  input  spec  file  will  be
1273       replaced with it.
1274
1275       Example of a custom macro placed in rpkg.macros file:
1276
1277           function git_commits_no {
1278               total_commits="$(git rev-list --all --count)"
1279               echo -n "$total_commits"
1280           }
1281
1282

AUTO-PACKING (DEPRECATED)

1284       Auto-packing  works  only  if  auto_pack configuration option is set to
1285       True and only if the content you are working with is  not  packed  (see
1286       `rpkg is-packed`).
1287
1288       When  invoking  `rpkg  srpm` on an unpacked content, rpkg will download
1289       external sources (if any) and then it will generate a tarball from  the
1290       whole content of the working directory named according to Source0 defi‐
1291       nition present in the associated .spec  file.   This  tarball  and  the
1292       .spec file are then passed to rpmbuild to generate the resulting srpm.
1293
1294

PACKED VS UNPACKED

1296       NOTE: This article relates to deprecated auto_pack feature.
1297
1298       While  it is quite intuitive what is packed content (.spec + tarballs +
1299       patches) and what is unpacked content  (.spec  +  original  application
1300       source  files), it might be useful to know how exactly rpkg differenti‐
1301       ates between these two.  You can go through the following  examples  to
1302       get overview how this tool exactly works.
1303
1304
1305   PACKED CONTENT:
1306           $ cd source0-present-example
1307           $ grep -E '(Source|Patch)' testpkg.spec
1308           Source0: foo.tar.gz
1309           $ ls .
1310           foo.tar.gz testpkg.spec
1311           $ rpkg make-source
1312           Could not execute make_source: Not an unpacked content.
1313           $ rpkg srpm
1314           Failed to get module name from Git url or pushurl.
1315           Wrote: source0-present-example/testpkg-1-1.fc25.src.rpm
1316
1317           The error about module name is caused by running `rpkg`
1318           on a plain directory content and not a Git repo. In this
1319           case, module name is read out from the spec file. The
1320           error about not being able to make source is expected for
1321           packed content (tarballs to be put into srpm are expected
1322           to be present already).
1323
1324           $ cd only-ignored-files-example
1325           $ grep -E '(Source|Patch)' testpkg.spec
1326           Source0: https://example.org/foo.tar.gz
1327           $ ls .
1328           README.md testpkg.spec
1329           $ rpkg make-source
1330           Could not execute make_source: Not an unpacked content.
1331           $ echo '%_disable_source_fetch 0' >> ~/.rpmmacros
1332           $ rpkg srpm
1333           Failed to get module name from Git url or pushurl
1334           warning:   Downloading   https://example.org/foo.tar.gz   to  only-
1335       ignored-files-example/foo.tar.gz
1336           Wrote: only-ignored-files-example/testpkg-1-1.fc25.src.rpm
1337
1338           In this example, sources are downloaded from network when
1339           srpm is being built. The %_disable_source_fetch rpm macro
1340           must be set to 0 and the tarball url must be valid for this
1341           to work. The content is recognized as packed because there
1342           are only ignored files in the directory (.spec and readmes).
1343
1344
1345   UNPACKED CONTENT:
1346           $ cd cpp-source-file-present-example
1347           $ git init .
1348           $ git remote add origin https://github.com/testpkg.git
1349           $ grep -E '(Source|Patch)' testpkg.spec
1350           Source0: foo.tar.gz
1351           $ ls .
1352           main.cpp testpkg.spec
1353           $ rpkg make-source
1354           Wrote: cpp-source-file-present-example/foo.tar.gz
1355           $ rpkg srpm
1356           Wrote: cpp-source-file-present-example/testpkg-1-1.fc25.src.rpm
1357
1358           foo.tar.gz (the only Source referenced from the .spec file) is
1359           not present and there is unignored main.cpp file that makes the
1360           content recognized as unpacked. When `rpkg make-source` is invoked,
1361           foo.tar.gz is created and will contain the main.cpp file (as
1362           well as the .spec metadata file but that is just because the
1363           whole content directory is packed). Note that the error about
1364           failing to get module name from Git url disappeared because
1365           we have run `git init .` and `git remote add ...`.
1366
1367

SEE ALSO

1369       https://pagure.io/rpkg-util/
1370
1371
1372
1373                                  2020-01-30                           rpkg(1)
Impressum