diff options
Diffstat (limited to 'docs/chapters')
| -rw-r--r-- | docs/chapters/building.sgml | 4 | ||||
| -rw-r--r-- | docs/chapters/import.sgml | 163 | ||||
| -rw-r--r-- | docs/chapters/intro.sgml | 2 |
3 files changed, 141 insertions, 28 deletions
diff --git a/docs/chapters/building.sgml b/docs/chapters/building.sgml index c7ac94b7..a028a4c4 100644 --- a/docs/chapters/building.sgml +++ b/docs/chapters/building.sgml @@ -61,7 +61,7 @@ <para>If you want to default to build in a separate build area, you can specify the directory to use in the <filename>gbp.conf</filename> file. <programlisting> -[git-buildpackage] +[buildpackage] # use a build area relative to the git repository export-dir=../build-area # to use the same build area for all packages use an absolute path: @@ -174,7 +174,7 @@ echo "done." by specifying the export directory: </para> <programlisting> -[git-buildpackage] +[buildpackage] # use a build area relative to the git repository export-dir = ../build-area # disable the since the sources are being exported first diff --git a/docs/chapters/import.sgml b/docs/chapters/import.sgml index ca2f927f..b86ca848 100644 --- a/docs/chapters/import.sgml +++ b/docs/chapters/import.sgml @@ -89,12 +89,41 @@ by version number. <option>--pristine-tar</option> option. This is recommended. </para> <para>To customize the commit message used by &gbp-import-orig;, use - the <option>--import-msg</option> option. This string is a standard - Python format string, into which the - <replaceable>version</replaceable> variable is interpolated. (i.e., - use <replaceable>%(version)s</replaceable> in your message to get - the imported upstream version). + the <option>--import-msg</option> option. This string is a + &pyformat;, into which the + <replaceable>version</replaceable> variable is + interpolated. (i.e., use <replaceable>%(version)s</replaceable> in + your message to get the imported upstream version). </para> + + <sect2> + <title>Recovering from errors</title> + <para>In case of an error &gbp-import-orig; will by default + rollback (undo) all changes it has done to the repository so far: + </para> + <programlisting> + $ &gbp; import-orig --verbose --filter='CVS/*' --filter='.bzr/*' --filter='.hg/*' --filter='.svn/*' --upstream-version=1.9 ../gif2apng-1.9.tar.gz + gbp:info: Importing '../gif2apng-1.9.tar.gz' to branch 'upstream' (filtering out ["'CVS/*'", "'.bzr/*'", "'.hg/*'", "'.svn/*'"])... + gbp:info: Source package is gif2apng + gbp:info: Upstream version is 1.9 + gbp:info: Merging to 'master' + gbp:error: Automatic merge failed. + gbp:error: Error detected, Will roll back changes. + gbp:info: Rolling back branch upstream by resetting it to a6733c1f1e190ac0ed4774abc3466e9986a6df5e + gbp:info: Rolling back branch pristine-tar by resetting it to 0ee24ac614c920e30af82d602882c2ee841c88e5 + gbp:info: Rolling back tag upstream/1.9 by deleting it + gbp:info: Rolling back branch master by resetting it to ce99782336e83a56e8e579b3cdadf93b0c19e1a8 + gbp:info: Rolling back failed merge of upstream/1.9 + gbp:error: Rolled back changes after import error. + </programlisting> + <para> + In this case the import failed due to a merge conflict. Other + reasons are running out of disk space, problems when generating + the pristine-tar delta. If you don't want &gbp-import-orig; to + undo changes made to the repository use + the <option>--no-rollback</option>. + </para> + </sect2> </sect1> <sect1 id="gbp.import.convert"> @@ -197,40 +226,95 @@ EOF <sect1 id="gbp.import.upstream-git"> <title>When upstream uses Git</title> <para> - If upstream already uses git for packaging, there are several ways to handle packaging. Two of them will - be described in a bit detail here: + If upstream uses &git; for development (and you don't want to + ignore that fact entirely), there are at least three ways to + handle packaging. The first one uses &git; exclusively and + creates the upstream tarballs from the upstream tag while the + second one still uses upstream tarballs but links your packaging + &git; history with upstreams &git; history. The third one also + uses a tarballs but does not link to the upstream history. </para> <sect2 id="gbp.import.upstream.git.notarball"> <title>No upstream tarballs</title> - <para>If upstream doesn't build upstream tarballs, or you don't care about them, the simplest - way is to clone upstream's repository and create a separate packaging branch in there. + <para>If upstream doesn't build upstream tarballs, or you + don't care about them, the simplest way is to clone + upstream's repository and create a separate packaging branch + in there. You will not need &gbp-import-orig; at all with + this workflow. &gbp-buildpackage; will handle creating the + upstream tarballs needed the Debian source package for you. </para> - <para> - In order to help &gbp-buildpackage; to find upstream tags, you need to specify the format - using the <option>--git-upstream-tag</option> command line option or the the <option>upstream-tag</option> - configuration variable. + For that to work you need to tell &gbp; how the + upstream tag format looks. Therefore you either + use the <option>--git-upstream-tag</option> command line option + or the <option>upstream-tag</option> configuration file + variable to specify upstream's tag format. </para> <para> - A common upstream format is to put a <replaceable>v</replaceable> in front of the version number. - In this case, the configuration option would look like: + A common upstream format is to put + a <replaceable>v</replaceable> in front of the version + number. In this case, the configuration option would look + like: </para> <programlisting> -[git-buildpackage] +[buildpackage] upstream-tag = v%(version)s </programlisting> <para> - <replaceable>version</replaceable> will be replaced with the upstream version number as read from - <filename>debian/changelog</filename>. + <replaceable>version</replaceable> will be replaced with the + upstream version number as determined from + <filename>debian/changelog</filename>. The <replaceable>%()s</replaceable> + might be familiar from &pyformat;s. + </para> + + <para> + Some upstreams use other formats though and don't separate + numbers by dots but rather by + underscore(<replaceable>_</replaceable>), + hyphen(<replaceable>-</replaceable>) or anything else. In + order to cope with that you can use version mangling of these + characters via substitution. The substitution works as + follows: + </para> +<programlisting> +[buildpackage] +upstream-tag = v%(version%.%_)s +</programlisting> + <para> + This means that each occurrence + of <replaceable>.</replaceable> will be replaced + by <replaceable>_</replaceable> in the upstream version + number. For example the upstream + version <replaceable>1.2.3</replaceable> as determined from + the <filename>debian/changelog</filename> will be looked up + as &git; tag <replaceable>v1_2_3</replaceable> by + &gbp-buildpackage;. </para> + <para> + If you want the substitution to be the <replaceable>%</replaceable> character + you have to escape it. E.g. <replaceable>%(version%-%\%)s</replaceable> will replace <replaceable>-</replaceable> with + <replaceable>%</replaceable>, transforming <replaceable>1-A.B.C</replaceable> to <replaceable>1%A.B.C</replaceable>. + Only a single replacement is supported and it can only replace a single character. + <warning> + <para> + Since some of the possible mangling characters + like <replaceable>_</replaceable> and <replaceable>%</replaceable> are also used to denote epochs and tilde revisions + these versions can't be reconstructed when mapping from &git; tags back to &debian; versions and will therefore break other tools + like &gbp-dch;. So use version mangling with care. It's better to come up with a Debian compatible tag format upstream, + see &dep14; for the currently used expansion rules for Debian versions. + </para> + </warning> + </para> + <para>If you're using &pristine-tar;, you can make &gbp-buildpackage; commit the generated tarball back to the pristine-tar branch by using the <option>--git-pristine-tar-commit</option> option. This will make sure - others building your package can regenerate the tarball you generated for building the &debian; package. + others building your package can exactly regenerate the + tarball you created when building the &debian; package. </para> - <sect3> + <sect3> <title>Step by step</title> <para>To not make any assumptions about &gbp;'s configuration, the following steps have all options given in its long versions on the command line. You can add these @@ -275,7 +359,7 @@ upstream-tag = v%(version)s </sect2> <sect2 id="gbp.import.upstream.git.tarball"> - <title>Upstream tarballs</title> + <title>Upstream tarballs and linked upstream history</title> <para>If you want to track upstream's &git; but continue to import the upstream tarballs, e.g. to make sure the tarball uploaded to &debian; has the same checksum as upstream's, you can use the <option>--upstream-vcs-tag</option> option @@ -289,6 +373,35 @@ upstream-tag = v%(version)s </para> </sect2> + <sect2 id="gbp.import.upstream.git.separate"> + <title>Upstream tarballs and separate upstream history</title> + <para> + If you want to have upstream's &git; history available but + don't want to link it to your packaging history you can + simply keep it as a separate history. E.g. if you already have + a &git; repository with your packaging, change into that + repository and do: +<programlisting> + &gitcmd; remote add upstream https://upstream.example.com/upstream.git + &gitcmd; fetch upstream +</programlisting> + This will pull in upstream's &git; history into your repo but since + your packaging commits and upstreams commits have no common + parents the two histories will stay nicely separated. + Of course you can browse it and cherry-pick from it but + any remote repos you push to will not get upstream's history + by default unless you push any of upstream's refs. + <warning> + <para> + Since &git; has a single tag namespace pushing + changes with <command>git push --tags</command> will + push upstream's tags (and therefore it's history) too so + be shure to only push dedicated tag names. + </para> + </warning> + </para> + </sect2> + </sect1> <sect1 id="gbp.branch.naming"> <title>Branch layout</title> @@ -298,7 +411,7 @@ upstream-tag = v%(version)s </para> <para> This layout is simple to get started but falls short if one needs to maintain several versions of - the package at the same time. Therefore the following layout is recommended: + the package at the same time. Therefore the following the &dep14; layout is recommended: </para> <variablelist> @@ -316,17 +429,17 @@ upstream-tag = v%(version)s </varlistentry> <varlistentry> <term> - upstream/<release> + upstream/latest </term> <listitem> <para> - the upstream sources for a release matching one of the above + the latest upstream sources. </para> </listitem> </varlistentry> <varlistentry> <term> - dfsg/<release> + dfsg/latest </term> <listitem> <para> diff --git a/docs/chapters/intro.sgml b/docs/chapters/intro.sgml index 8a6ee39c..b8048f94 100644 --- a/docs/chapters/intro.sgml +++ b/docs/chapters/intro.sgml @@ -87,7 +87,7 @@ you have to use <command>git push</command> in order to publish your changes to remote repositories like <ulink url="http://git.debian.org/">git.debian.org</ulink>; this can also be - automatized with &gbp-buildpackage;'s <option>post-tag</option> + automated with &gbp-buildpackage;'s <option>post-tag</option> hook.</para> </sect1> |