'\" -*- coding: us-ascii -*-
.if \n(.g .ds T< \\FC
.if \n(.g .ds T> \\F[\n[.fam]]
.de URL
\\$2 \(la\\$1\(ra\\$3
..
.if \n(.g .mso www.tmac
.TH gbp-import-ref 1 "21 March 2019" "" "git-buildpackage Manual"
.SH NAME
gbp-import-ref \- Update upstream sources when using Git only
.SH SYNOPSIS
'nh
.fi
.ad l
\fBgbp\ import-ref\fR \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
[\fB--version\fR] [\fB--help\fR] [\fB--verbose\fR] [\fB--color=\fR[auto|on|off]] [\fB--color-scheme=\fR \fICOLOR_SCHEME\fR] [\fB--upstream-version=\fR \fIversion\fR] [\fB--merge-mode=\fR \fI[auto|merge|replace]\fR] [\fB--upstream-branch=\fR \fIbranch_name\fR] [\fB--upstream-tag=\fR \fItag_format\fR] [\fB--upstream-tree=\fR \fI[BRANCH|VERSION|commit-id]\fR] [\fB--debian-branch=\fR \fIbranch_name\fR] [\fB--[no-]sign-tags\fR] [\fB--keyid=\fR \fIgpg-keyid\fR] [\fB--postimport=cmd\fR] [\fB--[no-]rollback\fR]
'in \n(.iu-\nxu
.ad b
'hy
.SH DESCRIPTION
\fBgbp\ import-ref\fR merges upstream git commits onto your \*(T<\fBdebian\-branch\fR\*(T>
You can either specifiy a branch to merge, give an upstream
version or specify the commit id directly. If no tag exists for the imported
commit it will be automatically created.
.SH OPTIONS
.TP 
\*(T<\fB\-\-version\fR\*(T>
Print version of the program, i.e. version of the git-buildpackage
suite
.TP 
\*(T<\fB\-v\fR\*(T>, \*(T<\fB\-\-verbose\fR\*(T>
Verbose execution
.TP 
\*(T<\fB\-h\fR\*(T>, \*(T<\fB\-\-help\fR\*(T>
Print help and exit
.TP 
\*(T<\fB\-\-color=\fR\*(T>[auto|on|off] 
Whether to use colored output.
.TP 
\*(T<\fB\-\-color\-scheme=\fR\*(T>\fICOLOR_SCHEME\fR 
Colors to use in output (when color is enabled). The format for
COLOR_SCHEME is
\&'<debug>:<info>:<warning>:<error>'.
Numerical values and color names are accepted, empty fields imply
the default color. For example,
\*(T<\fB\-\-git\-color\-scheme=\fR\*(T>\*(T<'cyan:34::'\*(T> would
show debug messages in cyan, info messages in blue and other messages
in default (i.e. warning and error messages in red).
.TP 
\*(T<\fB\-\-upstream\-version\fR\*(T>=\fIversion\fR, \*(T<\fB\-u\fR\*(T>\fIversion\fR
The upstream version to merge. The upstream tag to use will be determined via
the \*(T<\fB\-\-upstream\-tag\fR\*(T>.
.TP 
\*(T<\fB\-\-merge\-mode=\fR\*(T>\fI[auto|merge|replace]\fR
How to fold the upstream commits onto the
Debian packaging branch.

\fImerge\fR does a
Git \fBmerge\fR leaving you on your own in
case of merge conflict resolution.

\fIreplace\fR mode on the
other hand makes the head of the Debian packaging branch
identical to the newly imported tree but preserves the
content of the \*(T<\fIdebian/\fR\*(T> directory
while keeping the current head as well as the newly
imported tree as parents of the generated commit. This is
similar to a \*(T<\fBtheirs\fR\*(T> merge strategy while
preserving \*(T<\fIdebian/\fR\*(T>.

The default is \fIauto\fR which
uses \fIreplace\fR for 3.0 (quilt) packages
and \fImerge\fR otherwise.
.TP 
\*(T<\fB\-\-upstream\-branch\fR\*(T>=\fIbranch_name\fR 
The branch in the Git repository the upstream sources are
on. Default is \fIupstream\fR.
.TP 
\*(T<\fB\-\-upstream\-tag=\fR\*(T>\fItag-format\fR 
Use this tag format when looking up upstream tags,
default is \fIupstream/%(version)s\fR.
.TP 
\*(T<\fB\-\-upstream\-tree=\fR\*(T>\fI[BRANCH|VERSION|commit-id]\fR 
What to merge into the \*(T<\fBdebian\-branch\fR\*(T>.
\fIBRANCH\fR (the default) merges from the upstream branch.
\fIVERSION\fR looks for a tag determined from the given
upstream version number via the \*(T<\fB\-\-upstream\-version\fR\*(T> option.

Other values are interpreted as git commit id to merge from.
.TP 
\*(T<\fB\-\-debian\-branch\fR\*(T>=\fIbranch_name\fR 
The branch in the Git repository the Debian package is being
developed on, default is \fImaster\fR.
.TP 
\*(T<\fB\-\-[no\-]sign\-tags\fR\*(T> 
GPG sign all created tags.
.TP 
\*(T<\fB\-\-keyid=\fR\*(T>\fIgpg-keyid\fR 
Use this \fIkeyid\fR
for gpg signing tags.
.TP 
\*(T<\fB\-\-import\-msg=\fR\*(T>\fImsg-format\fR 
Use this format string for the commit message when importing upstream
versions, default is
\fINew upstream version %(version)s\fR.
.TP 
\*(T<\fB\-\-postimport=\fR\*(T>\fIcmd\fR
Run \fIcmd\fR after the import. The
hook gets the following environment variables passed:
.RS 
.TP 
\fBGBP_BRANCH\fR
The name of the Debian packaging branch
.TP 
\fBGBP_TAG\fR
The name of the just created upstream tag
.TP 
\fBGBP_UPSTREAM_VERSION\fR
The just imported upstream version
.TP 
\fBGBP_DEBIAN_VERSION\fR
The Debian version of the package with a Debian
revision of '-1'
.RE
.TP 
\*(T<\fB\-\-[no\-]rollback\fR\*(T>
Rollback changes in case of an error.
.SH EXAMPLES
Merge commits from the \*(T<\fBupstream\-branch\fR\*(T> into the \*(T<\fBdebian\-branch\fR\*(T>
creating a tag for the version \fI0.0~git20180524\fR:
.PP
.nf
\*(T<
    \fBgbp\ import\-ref\fR \-\-upstream\-tree=BRANCH \-u0.0~git20180524\*(T>
.fi
.PP
Merge commits from the the tag corresponding to version \fI1.0\fR:
.PP
.nf
\*(T<
    \fBgbp\ import\-ref\fR \-\-upstream\-tree=VERSION \-u1.0\*(T>
.fi
.PP
Merge commits given by a SHA1 creating a tag for the version
\fI0.0~git20180524\fR
.PP
.nf
\*(T<
    \fBgbp\ import\-ref\fR \-\-upstream\-tree=c4398912c \-u0.0~git20180524\*(T>
.fi
.SH "CONFIGURATION FILES"
Several \*(T<\fIgbp.conf\fR\*(T> files are parsed 
to set defaults for the above command-line arguments. See the
\fBgbp.conf\fR(5) manpage for details.
.SH "SEE ALSO"
\fBgbp-buildpackage\fR(1),
\fBgbp-import-dsc\fR(1),
\fBgbp-import-dscs\fR(1),
\fBgbp-dch\fR(1),
\fBgbp.conf\fR(5),
\fBuscan\fR(1),
\fBdebuild\fR(1),
\fBgit\fR(1),
\fBpristine-tar\fR(1),
.URL file:///usr/share/doc/git-buildpackage/manual-html/index.html "       The Git-Buildpackage Manual"
.SH AUTHOR
Guido G\(:unther <\*(T<agx@sigxcpu.org\*(T>>