Add support for tracking jigdo back-references
[jigit.git] / mkjigsnap.8
1 .TH MKJIGSNAP 8 "September 2004" "Jigit jigdo tools"
2 .SH NAME
3 mkjigsnap \- Create a snapshot tree on a jigdo server
4 .SH SYNOPSIS
5 .\" The single-jigdo command line
6 .B mkjigsnap
7 [OPTIONS]
8 <\-d \f snapshot_dir\fR>
9 <\-j \f jigdo_file\fR>
10 <\-k \f keyword\fR>
11 <\-m \f mirror\fR>
12 <\-n \f CD_name\fR>
13 <\-o \f output_directory\fR>
14 <\-t \f template_file\fR>
15 .\" The multi-jigdo command line
16 .br
17 .B mkjigsnap
18 [OPTIONS]
19 <\-b \f backref_file\fR>
20 <\-d \f snapshot_dir\fR>
21 <\-m \f mirror\fR>
22 <\-J \f jigdo_list\fR>
23 <\-j \f jigdo_file\fR>
24 <\-k \f keyword\fR>
25 .SH DESCRIPTION
26 .PP
27 mkjigsnap creates snapshot directories for use by other jigdo
28 tools. It can be run in two distinct modes:
29
30 .SS "Jigit / single-jigdo mode"
31
32 To build a jigit .conf file for a single jigdo file: add the "\-n"
33 option with a CD name on the command line and only specify a single
34 jigdo to work with using "\-j".
35
36 Required arguments for this mode:
37 .TP
38 \fB\-d snapshot_dir\fR
39 Specify the output directory name to be used for the snapshot tree
40 (e.g. 20041011, rc1). In single-jigdo mode this will be
41 .B relative
42 to the output directory.
43 .TP
44 \fB\-j jigdo_file\fR
45 Specify the location of the jigdo file to be used.
46 .TP
47 \fB\-m mirror\fR
48 Specify the location of the mirror containing all the files
49 needed. This
50 .B must
51 be on the same filesystem as the output directory, as hard links will
52 be used to create the snapshot efficiently.
53 .TP
54 \fB\-n CD_name\fR
55 Specify the output name of the CD for jigit (e.g. warty, sarge-i386-1).
56 .TP
57 \fB\-o output_directory\fR
58 Specify the output location for the jigdo, template, conf and
59 snapshot. This
60 .B must
61 be on the same filesystem as the mirror, as hard links will be used to
62 create the snapshot efficiently.
63 .TP
64 \fB\-t template_file\fR
65 Specify the location of the template file to be used.
66
67 .SS "Multi-jigdo mode"
68
69 To build a snapshot tree for (potentially multiple) jigdo files: do
70 not specify the "\-n" option, and list as many jigdo files as desired,
71 either on the command line using multiple "\-j <jigdo>" options or
72 (better) via a file listing them with the "\-J" option.
73
74 Required arguments for this mode:
75 .TP
76 \fB\-d snapshot_dir\fR
77 Specify the output directory name to be used for the snapshot tree
78 (e.g. 20041011, rc1). 
79 .TP
80 \fB\-J jigdo_list\fR
81 Specify the location of a file listing the jigdo files to be used. May
82 be repeated multiple times for multiple list files if desired.
83 .TP
84 \fB\-j jigdo_file\fR
85 Specify the location of the jigdo file to be used. May be repeated
86 multiple times for multiple jigdo files, but it's better to use the
87 "-J" option to point at a file containing a list of jigdo files
88 instead.
89 .TP
90 \fB\-k keyword\fR
91 Specify the "keywords" which are used in the jigdo files (e.g. Debian,
92 Non-US, Ubuntu).
93 .TP
94 \fB\-m mirror\fR
95 Specify the location of the mirror containing all the files
96 needed. This
97 .B must
98 be on the same filesystem as the snapshot directory, as hard links
99 will be used to create the snapshot efficiently.
100
101 .SS "Options"
102
103 Optional arguments for both modes:
104 .TP
105 \fB\-b backref_file\fR
106 If using a fail_log, also keep track of which jigdo files correspond
107 to each missing file, and output the details in the backref_file.
108 .TP
109 \fB\-f fail_log\fR
110 If any files are required by the specific jigdo files but are not
111 available in the mirror, list them in the output file fail_log for
112 reference.
113 .TP
114 \fB\-i ignore_list\fR
115 If any files are required by the specific jigdo files but are not
116 available in the mirror, list them in the ignore_list file to supress
117 errors about them.
118
119 .SH EXAMPLES
120 .TP
121 mkjigsnap \-o /tmp/mjs-test \-n mjs-test \-m /tmp/mirror \-j
122 ~/jigdo/update/debian-update-3.0r2.01-i386.jigdo \-t
123 ~/jigdo/update/debian-update-3.0r2.01-i386.template \-k Debian \-k
124 Non-US \-d 20041017
125
126 This command is an example of single-jigdo mode, used for Ubuntu jigit
127 generation. It creates a single jigit conf file using the supplied
128 jigdo/template file pair, looking for jigdo references to files in the
129 "Debian" and "Non-US" areas. Output the files into /tmp/mjs-test and
130 call them "mjs-test.<ext>", creating a snapshot of the needed files in
131 /tmp/mjs-test/20041017 by linking files from /tmp/mirror as needed.
132
133 .TP
134 mkjigsnap \-m /org/ftp/debian \-J ~/jigdo.list \-k Debian
135 \-d /org/jigdo-area/snapshot/Debian \-f ~/mkjigsnap-failed.log \-i
136 ~/mkjigsnap-ignore.list
137
138 This command is an example of multi-jigdo mode, as run to keep
139 http://us.cdimage.debian.org/cdimage/snapshot/ up to date. This reads
140 in all the jigdo files listed in ~/jigdo.list, building a list of all
141 the files referenced in the "Debian" area. It will then attempt to
142 build a snapshot tree of all those files under
143 /org/jigdo-area/snapshot/Debian by linking from /org/ftp/debian. Any
144 files that are missing will be listed into the output "missing" file
145 ~/mkjigsnap-failed.log for later checking, UNLESS they are already
146 listed in the "ignore" file ~/mkjigsnap-ignore.list.
147
148 .SH "SEE ALSO"
149 \fBjigdo-file\fP(1), \fBjigit\fP(1), \fBjigdump\fP(1) and \fBmkimage\fP(1).
150 .SH "COPYRIGHT"
151 Copyright 2004 - 2014 Steve McIntyre (steve@einval.com)
152 .PP
153 mkjigsnap may be copied under the terms and conditions of version 2 of
154 the GNU General Public License, as published by the Free Software
155 Foundation (Cambridge, MA, USA).
156 .SH "AUTHOR"
157 Written by Steve McIntyre (steve@einval.com)