.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DEBCHECKOUT 1"
.TH DEBCHECKOUT 1 "2018-01-23" "Debian Utilities" " "
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
debcheckout \- checkout the development repository of a Debian package
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.IP "\fBdebcheckout\fR [\fI\s-1OPTIONS\s0\fR] \fI\s-1PACKAGE\s0\fR [\fI\s-1DESTDIR\s0\fR]" 4
.IX Item "debcheckout [OPTIONS] PACKAGE [DESTDIR]"
.PD 0
.IP "\fBdebcheckout\fR [\fI\s-1OPTIONS\s0\fR] \fI\s-1REPOSITORY_URL\s0\fR [\fI\s-1DESTDIR\s0\fR]" 4
.IX Item "debcheckout [OPTIONS] REPOSITORY_URL [DESTDIR]"
.IP "\fBdebcheckout\fR \fB\-\-help\fR" 4
.IX Item "debcheckout --help"
.PD
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBdebcheckout\fR retrieves the information about the Version Control System used
to maintain a given Debian package (the \fI\s-1PACKAGE\s0\fR argument), and then checks
out the latest (potentially unreleased) version of the package from its
repository.  By default the repository is checked out to the \fI\s-1PACKAGE\s0\fR
directory; this can be overridden by providing the \fI\s-1DESTDIR\s0\fR argument.
.PP
The information about where the repository is available is expected to be found
in \fBVcs\-*\fR fields available in the source package record. For example, the \fBvim\fR
package exposes such information with a field like \fBVcs\-Hg: http://hg.debian.org/hg/pkg\-vim/vim\fR, you can see it by grepping through
\&\fBapt-cache showsrc vim\fR.
.PP
If more than one source package record containing \fBVcs\-*\fR fields is available,
\&\fBdebcheckout\fR will select the record with the highest version number.
Alternatively, a particular version may be selected from those available by
specifying the package name as \fI\s-1PACKAGE\s0\fR=\fI\s-1VERSION\s0\fR.
.PP
If you already know the \s-1URL\s0 of a given repository you can invoke
\&\fBdebcheckout\fR directly on it, but you will probably need to pass the
appropriate \fB\-t\fR flag. That is, some heuristics are in use to guess
the repository type from the \s-1URL\s0; if they fail, you might want to
override the guessed type using \fB\-t\fR.
.PP
The currently supported version control systems are: Arch (arch), Bazaar (bzr), \s-1CVS \s0(cvs),
Darcs (darcs), Git (git), Mercurial (hg) and Subversion (svn).
.SH "OPTIONS"
.IX Header "OPTIONS"
\&\fB\s-1GENERAL OPTIONS\s0\fR
.IP "\fB\-a\fR, \fB\-\-auth\fR" 4
.IX Item "-a, --auth"
Work in authenticated mode; this means that for known repositories (mainly those
hosted on \fIhttps://alioth.debian.org\fR) \s-1URL\s0 rewriting is attempted before
checking out, to ensure that the repository can be committed to. For example,
for Subversion repositories hosted on alioth this means that
\&\fIsvn+ssh://svn.debian.org/...\fR will be used instead of
\&\fIsvn://svn.debian.org/...\fR.
.Sp
There are built-in rules for alioth.debian.org and github.com. Other hosts
can be configured using \fB\s-1DEBCHECKOUT_AUTH_URLS\s0\fR.
.IP "\fB\-d\fR, \fB\-\-details\fR" 4
.IX Item "-d, --details"
Only print a list of detailed information about the package
repository, without checking it out; the output format is a list of
fields, each field being a pair of TAB-separated field name and field
value. The actual fields depend on the repository type. This action
might require a network connection to the remote repository.
.Sp
Also see \fB\-p\fR. This option and \fB\-p\fR are mutually exclusive.
.IP "\fB\-h\fR, \fB\-\-help\fR" 4
.IX Item "-h, --help"
Print a detailed help message and exit.
.IP "\fB\-p\fR, \fB\-\-print\fR" 4
.IX Item "-p, --print"
Only print a summary about package repository information, without
checking it out; the output format is TAB-separated with two fields:
repository type, repository \s-1URL.\s0 This action works offline, it only
uses \*(L"static\*(R" information as known by \s-1APT\s0's cache.
.Sp
Also see \fB\-d\fR. This option and \fB\-d\fR are mutually exclusive.
.IP "\fB\-P\fR \fIpackage\fR, \fB\-\-package\fR \fIpackage\fR" 4
.IX Item "-P package, --package package"
When checking out a repository \s-1URL,\s0 instead of trying to guess the package name
from the \s-1URL,\s0 use this package name.
.IP "\fB\-t\fR \fI\s-1TYPE\s0\fR, \fB\-\-type\fR \fI\s-1TYPE\s0\fR" 4
.IX Item "-t TYPE, --type TYPE"
Override the repository type (which defaults to some heuristics based
on the \s-1URL\s0 or, in case of heuristic failure, the fallback \*(L"svn\*(R");
should be one of the currently supported repository types.
.IP "\fB\-u\fR \fI\s-1USERNAME\s0\fR, \fB\-\-user\fR \fI\s-1USERNAME\s0\fR" 4
.IX Item "-u USERNAME, --user USERNAME"
Specify the login name to be used in authenticated mode (see \fB\-a\fR). This option
implies \fB\-a\fR: you don't need to specify both.
.IP "\fB\-f\fR \fI\s-1FILE\s0\fR, \fB\-\-file\fR \fI\s-1FILE\s0\fR" 4
.IX Item "-f FILE, --file FILE"
Specify that the named file should be extracted from the repository and placed
in the destination directory. May be used more than once to extract multiple
files.
.IP "\fB\-\-source=never\fR|\fBauto\fR|\fBdownload-only\fR|\fBalways\fR" 4
.IX Item "--source=never|auto|download-only|always"
Some packages only place the \fIdebian\fR directory in version control.
\&\fBdebcheckout\fR can retrieve the remaining parts of the source using \fBapt-get
source\fR and move the files into the checkout.
.RS 4
.IP "\fBnever\fR" 4
.IX Item "never"
Only use the repository.
.IP "\fBauto\fR (default)" 4
.IX Item "auto (default)"
If the repository only contains the \fIdebian\fR directory, retrieve the source
package, unpack it, and also place the \fI.orig.tar.gz\fR file into the current
directory. Else, do nothing.
.IP "\fBdownload-only\fR" 4
.IX Item "download-only"
Always retrieve the \fI.orig.tar.gz\fR file, but do not unpack it.
.IP "\fBalways\fR" 4
.IX Item "always"
Always retrieve the \fI.orig.tar.gz\fR file, and if the repository only contains the
\&\fIdebian\fR directory, unpack it.
.RE
.RS 4
.RE
.PP
\&\fBVCS-SPECIFIC \s-1OPTIONS\s0\fR
.PP
\&\fIGIT-SPECIFIC \s-1OPTIONS\s0\fR
.IP "\fB\-\-git\-track\fR \fI\s-1BRANCHES\s0\fR" 4
.IX Item "--git-track BRANCHES"
Specify a list of remote branches which will be set up for tracking
(as in \fBgit branch \-\-track\fR, see \fBgit-branch\fR(1)) after the remote
Git repository has been cloned. The list should be given as a
space-separated list of branch names.
.Sp
As a shorthand, the string "\fB*\fR" can be given to require tracking of all
remote branches.
.SH "CONFIGURATION VARIABLES"
.IX Header "CONFIGURATION VARIABLES"
The two configuration files \fI/etc/devscripts.conf\fR and
\&\fI~/.devscripts\fR are sourced by a shell in that order to set
configuration variables. Command line options can be used to override
configuration file settings. Environment variable settings are ignored
for this purpose. The currently recognised variables are:
.IP "\fB\s-1DEBCHECKOUT_AUTH_URLS\s0\fR" 4
.IX Item "DEBCHECKOUT_AUTH_URLS"
This variable should be a space separated list of Perl regular
expressions and replacement texts, which must come in pairs: \fI\s-1REGEXP\s0\fR
\&\fI\s-1TEXT\s0\fR \fI\s-1REGEXP\s0\fR \fI\s-1TEXT\s0\fR ... and so on. Each pair denotes a substitution which
is applied to repository URLs if other built-in means of building URLs
for authenticated mode (see \fB\-a\fR) have failed.
.Sp
References to matching substrings in the replacement texts are
allowed as usual in Perl by the means of \fB\f(CB$1\fB\fR, \fB\f(CB$2\fB\fR, ... and so on.
.Sp
This setting can be used to enable authenticated mode for most repositories
out there.  Note that the Debian repositories on alioth.debian.org
($vcs.debian.org) are implicitly defined.
.Sp
Here is a sample snippet suitable for the configuration files:
.Sp
.Vb 4
\& DEBCHECKOUT_AUTH_URLS=\*(Aq
\&  ^\ew+://(svn\e.example\e.com)/(.*)    svn+ssh://$1/srv/svn/$2
\&  ^\ew+://(git\e.example\e.com)/(.*)    git+ssh://$1/home/git/$2
\& \*(Aq
.Ve
.Sp
Note that whitespace is not allowed in either regexps or
replacement texts. Also, given that configuration files are sourced by
a shell, you probably want to use single quotes around the value of
this variable.
.IP "\fB\s-1DEBCHECKOUT_SOURCE\s0\fR" 4
.IX Item "DEBCHECKOUT_SOURCE"
This variable determines under what scenarios the associated orig.tar.gz for a
package will be downloaded.  See the \fB\-\-source\fR option for a description of
the values.
.IP "\fB\s-1DEBCHECKOUT_USER\s0\fR" 4
.IX Item "DEBCHECKOUT_USER"
This variable sets the username for authenticated mode. It can be overridden
with the \fB\-\-user\fR option. Setting this variable does not imply the use of
authenticated mode, it still has to be activated with \fB\-\-auth\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBapt-cache\fR(8), Section 6.2.5 of the Debian Developer's Reference (for
more information about \fBVcs\-*\fR fields): \fIhttps://www.debian.org/doc/developers\-reference/best\-pkging\-practices.html#bpp\-vcs\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
\&\fBdebcheckout\fR and this manpage have been written by Stefano Zacchiroli
<\fIzack@debian.org\fR>.