1DEBCHECKOUT(1)                                                  DEBCHECKOUT(1)
2
3
4

NAME

6       debcheckout - checkout the development repository of a Debian package
7

SYNOPSIS

9       debcheckout [OPTIONS] PACKAGE [DESTDIR]
10       debcheckout [OPTIONS] REPOSITORY_URL [DESTDIR]
11       debcheckout --help
12

DESCRIPTION

14       debcheckout retrieves the information about the Version Control System
15       used to maintain a given Debian package (the PACKAGE argument), and
16       then checks out the latest (potentially unreleased) version of the
17       package from its repository.  By default the repository is checked out
18       to the PACKAGE directory; this can be overridden by providing the
19       DESTDIR argument.
20
21       The information about where the repository is available is expected to
22       be found in Vcs-* fields available in the source package record. For
23       example, the vim package exposes such information with a field like
24       Vcs-Hg: http://hg.debian.org/hg/pkg-vim/vim, you can see it by grepping
25       through apt-cache showsrc vim.
26
27       If more than one source package record containing Vcs-* fields is
28       available, debcheckout will select the record with the highest version
29       number.  Alternatively, a particular version may be selected from those
30       available by specifying the package name as PACKAGE=VERSION.
31
32       If you already know the URL of a given repository you can invoke
33       debcheckout directly on it, but you will probably need to pass the
34       appropriate -t flag. That is, some heuristics are in use to guess the
35       repository type from the URL; if they fail, you might want to override
36       the guessed type using -t.
37
38       The currently supported version control systems are: Arch (arch),
39       Bazaar (bzr), CVS (cvs), Darcs (darcs), Git (git), Mercurial (hg) and
40       Subversion (svn).
41

OPTIONS

43       GENERAL OPTIONS
44
45       -a, --auth
46           Work in authenticated mode; this means that for known repositories
47           (mainly those hosted on https://salsa.debian.org) URL rewriting is
48           attempted before checking out, to ensure that the repository can be
49           committed to. For example, for Git repositories hosted on Salsa
50           this means that git@salsa.debian.org:...git will be used instead of
51           https://salsa.debian.org/...git.
52
53           There are built-in rules for salsa.debian.org, alioth.debian.org
54           and github.com. Other hosts can be configured using
55           DEBCHECKOUT_AUTH_URLS.
56
57       -d, --details
58           Only print a list of detailed information about the package
59           repository, without checking it out; the output format is a list of
60           fields, each field being a pair of TAB-separated field name and
61           field value. The actual fields depend on the repository type. This
62           action might require a network connection to the remote repository.
63
64           Also see -p. This option and -p are mutually exclusive.
65
66       -h, --help
67           Print a detailed help message and exit.
68
69       -p, --print
70           Only print a summary about package repository information, without
71           checking it out; the output format is TAB-separated with two
72           fields: repository type, repository URL. This action works offline,
73           it only uses "static" information as known by APT's cache.
74
75           Also see -d. This option and -d are mutually exclusive.
76
77       -P package, --package package
78           When checking out a repository URL, instead of trying to guess the
79           package name from the URL, use this package name.
80
81       -t TYPE, --type TYPE
82           Override the repository type (which defaults to some heuristics
83           based on the URL or, in case of heuristic failure, the fallback
84           "git"); should be one of the currently supported repository types.
85
86       -u USERNAME, --user USERNAME
87           Specify the login name to be used in authenticated mode (see -a).
88           This option implies -a: you don't need to specify both.
89
90       -f FILE, --file FILE
91           Specify that the named file should be extracted from the repository
92           and placed in the destination directory. May be used more than once
93           to extract multiple files.
94
95       --source=never|auto|download-only|always
96           Some packages only place the debian directory in version control.
97           debcheckout can retrieve the remaining parts of the source using
98           apt-get source and move the files into the checkout.
99
100           never
101               Only use the repository.
102
103           auto (default)
104               If the repository only contains the debian directory, retrieve
105               the source package, unpack it, and also place the .orig.tar.gz
106               file into the current directory. Else, do nothing.
107
108           download-only
109               Always retrieve the .orig.tar.gz file, but do not unpack it.
110
111           always
112               Always retrieve the .orig.tar.gz file, and if the repository
113               only contains the debian directory, unpack it.
114
115       VCS-SPECIFIC OPTIONS
116
117       GIT-SPECIFIC OPTIONS
118
119       --git-track BRANCHES
120           Specify a list of remote branches which will be set up for tracking
121           (as in git branch --track, see git-branch(1)) after the remote Git
122           repository has been cloned. The list should be given as a space-
123           separated list of branch names.
124
125           As a shorthand, the string "*" can be given to require tracking of
126           all remote branches.
127

CONFIGURATION VARIABLES

129       The two configuration files /etc/devscripts.conf and ~/.devscripts are
130       sourced by a shell in that order to set configuration variables.
131       Command line options can be used to override configuration file
132       settings. Environment variable settings are ignored for this purpose.
133       The currently recognised variables are:
134
135       DEBCHECKOUT_AUTH_URLS
136           This variable should be a space separated list of Perl regular
137           expressions and replacement texts, which must come in pairs: REGEXP
138           TEXT REGEXP TEXT ... and so on. Each pair denotes a substitution
139           which is applied to repository URLs if other built-in means of
140           building URLs for authenticated mode (see -a) have failed.
141
142           References to matching substrings in the replacement texts are
143           allowed as usual in Perl by the means of $1, $2, ... and so on.
144
145           This setting is used to configure the "authenticated mode" location
146           for repositories. The Debian repositories on salsa.debian.org are
147           implicitly defined, as is github.com.
148
149           Here is a sample snippet suitable for the configuration files:
150
151            DEBCHECKOUT_AUTH_URLS='
152             ^\w+://(svn\.example\.com)/(.*)    svn+ssh://$1/srv/svn/$2
153             ^\w+://(git\.example\.com)/(.*)    git+ssh://$1/home/git/$2
154            '
155
156           Note that whitespace is not allowed in either regexps or
157           replacement texts. Also, given that configuration files are sourced
158           by a shell, you probably want to use single quotes around the value
159           of this variable.
160
161       DEBCHECKOUT_SOURCE
162           This variable determines under what scenarios the associated
163           orig.tar.gz for a package will be downloaded.  See the --source
164           option for a description of the values.
165
166       DEBCHECKOUT_USER
167           This variable sets the username for authenticated mode. It can be
168           overridden with the --user option. Setting this variable does not
169           imply the use of authenticated mode, it still has to be activated
170           with --auth.
171

SEE ALSO

173       apt-cache(8), Section 6.2.5 of the Debian Developer's Reference (for
174       more information about Vcs-* fields):
175       https://www.debian.org/doc/developers-reference/best-pkging-practices.html#bpp-vcs.
176

AUTHOR

178       debcheckout and this manpage have been written by Stefano Zacchiroli
179       <zack@debian.org>.
180
181
182
183Debian Utilities                  2021-05-03                    DEBCHECKOUT(1)
Impressum