Signed-off-by: Paul Hardy <unifoundry@gmail.com>
If there is no or little distinction between
(i) developers who are entitled to upload (push) and
(ii) repository administrators,
If there is no or little distinction between
(i) developers who are entitled to upload (push) and
(ii) repository administrators,
-then a it is sufficient to provide a
-git server with a unix account for each user who will pushing,
+then it is sufficient to provide a
+git server with a unix account for each user who will be pushing,
perhaps using ssh restricted commands.
=item Debian-format archive (repository)
perhaps using ssh restricted commands.
=item Debian-format archive (repository)
Setting up reprepro is not covered in this tutorial.
Instead, we assume you already have reprepro working.
Setting up reprepro is not covered in this tutorial.
Instead, we assume you already have reprepro working.
-You should also write appropriate dput configuration,
+You should also write an appropriate dput configuration file,
since dgit uses dput to upload packages to the archive.
This will involve choosing a dput host name.
That's probably your distro name, I<distro>.
since dgit uses dput to upload packages to the archive.
This will involve choosing a dput host name.
That's probably your distro name, I<distro>.
If you always have a git repository for every package in your archive,
perhaps because you never use dput/dupload, and always dgit push,
If you always have a git repository for every package in your archive,
perhaps because you never use dput/dupload, and always dgit push,
-Set C<git-check> to B<true>.
+set C<git-check> to B<true>.
Otherwise, set C<git-check> to a url prefix - ideally, https.
dgit clone will try to fetch
Otherwise, set C<git-check> to a url prefix - ideally, https.
dgit clone will try to fetch
When a user who can push runs dgit,
dgit uses ssh to access the git server.
When a user who can push runs dgit,
dgit uses ssh to access the git server.
-To make ssh restricted command easier,
+To make the ssh restricted command easier,
and for the benefit of dgit-repos-server,
dgit's ssh commands
each start with a parseable commentish rune.
and for the benefit of dgit-repos-server,
dgit's ssh commands
each start with a parseable commentish rune.
=back
Pass I<--stat> just to see the list of changed files, which is useful
=back
Pass I<--stat> just to see the list of changed files, which is useful
-to determine whether there are any new or deleted files to may need
+to determine whether there are any new or deleted files that may need
accounting for in your copyright file.
If you obtained a tarball from upstream, you are ready to try a build.
accounting for in your copyright file.
If you obtained a tarball from upstream, you are ready to try a build.
the last upload, it is not possible for dgit to make your history
fast-forwarding from the history on B<dgit-repos>. In such cases you
will have to pass I<--overwrite> to dgit. git-debrebase will normally
the last upload, it is not possible for dgit to make your history
fast-forwarding from the history on B<dgit-repos>. In such cases you
will have to pass I<--overwrite> to dgit. git-debrebase will normally
-tell you if this is will be needed.
+tell you if this will be needed.
Right before uploading, if you did not just already do so, you might
want to have git-debrebase(1) shuffle your branch such that the Debian
Right before uploading, if you did not just already do so, you might
want to have git-debrebase(1) shuffle your branch such that the Debian
-If that fails, because your branch and the NMUers work represent
+If that fails, because your branch and the NMUers' work represent
divergent branches of development, you have a number of options. Here
we describe the two simplest.
divergent branches of development, you have a number of options. Here
we describe the two simplest.
Alternatively,
if this was the first ever dgit push of the package,
you can avoid this merge commit by
Alternatively,
if this was the first ever dgit push of the package,
you can avoid this merge commit by
-passing C<--deliberately-not-fast-forward>.
+passing C<--deliberately-not-fast-forward>
instead of C<--overwrite>.
This avoids introducing a new origin commit into
your git history.
instead of C<--overwrite>.
This avoids introducing a new origin commit into
your git history.
a sponsoring DD (or DM)
can collaborate and publish using git.
a sponsoring DD (or DM)
can collaborate and publish using git.
-The sponsor must to be intending to use dgit for the upload.
+The sponsor must be intending to use dgit for the upload.
(If the sponsor does not use dgit,
it is not possible to properly publish
a sponsee's git branch.)
(If the sponsor does not use dgit,
it is not possible to properly publish
a sponsee's git branch.)
your desperate last resort is to try
using the same version number
as the official package for your own package.
your desperate last resort is to try
using the same version number
as the official package for your own package.
-(The version is controlled by C<debian/changelog> - see above).
+(The version is controlled by C<debian/changelog> - see above.)
This is not ideal because it makes it hard to tell what is installed,
and because it will mislead and confuse apt.
This is not ideal because it makes it hard to tell what is installed,
and because it will mislead and confuse apt.
Set up the working tree's
.B .git/info/attributes
to disable all transforming attributes for all files.
Set up the working tree's
.B .git/info/attributes
to disable all transforming attributes for all files.
-This is done by defining a macro attribute
-.B dgit-defuse-attrs
+This is done by defining a macro attribute,
+.B dgit-defuse-attrs,
and applying it to
.BR * .
For why, see
and applying it to
.BR * .
For why, see
in .git/info/attributes,
but it is insufficient,
because it was made by an earlier version of dgit
in .git/info/attributes,
but it is insufficient,
because it was made by an earlier version of dgit
-and git has since introduced new transforming attributes,
-modifies the macro to disable the newer transformations.
+and git has since introduced new transforming attributes;
+this modifies the macro to disable the newer transformations.
(If there is already a macro attribute line
.B [attr]dgit-defuse-attrs
(If there is already a macro attribute line
.B [attr]dgit-defuse-attrs
dgit will make a pseudomerge
so that the result is necessarily fast forward
from the existing branch.
dgit will make a pseudomerge
so that the result is necessarily fast forward
from the existing branch.
-Otherwise, if branch already exists,
+Otherwise, if the branch already exists,
dgit will stop with an error message.
If
dgit will stop with an error message.
If
generated for you by dgit,
so that the archive software can give effect to your intent,
and
generated for you by dgit,
so that the archive software can give effect to your intent,
and
-for the benefit humans looking at the history.
+for the benefit of humans looking at the history.
The meanings of
.IR something s
understood in the context of Debian are discussed below:
The meanings of
.IR something s
understood in the context of Debian are discussed below:
directory.)
.TP
.BR --quilt=nocheck " | " --no-quilt-fixup
directory.)
.TP
.BR --quilt=nocheck " | " --no-quilt-fixup
-Do not check whether up source format `3.0 (quilt)' metadata needs
+Do not check whether source format `3.0 (quilt)' metadata needs
fixing up. If you use this option and the metadata did in fact need
fixing up, dgit push will fail.
.TP
fixing up. If you use this option and the metadata did in fact need
fixing up, dgit push will fail.
.TP
.TP
.BI -C changesfile
Specifies the .changes file which is to be uploaded. By default
.TP
.BI -C changesfile
Specifies the .changes file which is to be uploaded. By default
-dgit push looks for single .changes file in the parent directory whose
+dgit push looks for a single .changes file in the parent directory whose
filename suggests it is for the right package and version.
If the specified
filename suggests it is for the right package and version.
If the specified
.TP
.BR dgit-distro. \fIdistro\fR .clean-mode-newer
Like .clean-mode,
.TP
.BR dgit-distro. \fIdistro\fR .clean-mode-newer
Like .clean-mode,
-but ignored if the value does not make sense to this version of dgit.
+but ignored if the value is unknown to this version of dgit.
Setting both .clean-mode and .clean-mode-newer is useful
to provide a single git config compatible with different dgit versions.
.TP
Setting both .clean-mode and .clean-mode-newer is useful
to provide a single git config compatible with different dgit versions.
.TP
.TP
.BI dgit-distro. distro .setup-useremail
Whether to set user.name and user.email in new git trees.
.TP
.BI dgit-distro. distro .setup-useremail
Whether to set user.name and user.email in new git trees.
-True by default. Ignored for dgit setup-setup-useremail, which does it anyway.
+True by default. Ignored for dgit setup-useremail, which does it anyway.
.TP
.BI dgit-distro. distro .setup-mergechangelogs
.TP
.BI dgit-distro. distro .setup-mergechangelogs
-Whether to setup a merge driver which uses dpkg-mergechangelogs for
+Whether to set up a merge driver which uses dpkg-mergechangelogs for
debian/changelog. True by default. Ignored for dgit
setup-mergechangelogs, which does it anyway.
.TP
debian/changelog. True by default. Ignored for dgit
setup-mergechangelogs, which does it anyway.
.TP
To pass several options, configure multiple values in git config
(with git config --add). The options for
.BI dgit.default.opts- cmd
To pass several options, configure multiple values in git config
(with git config --add). The options for
.BI dgit.default.opts- cmd
.BI dgit-distro. distro /push.opts- cmd
.BI dgit-distro. distro /push.opts- cmd
-and are all used, followed by options from dgit's command line.
+are all used, followed by options from dgit's command line.
.SH ACCESS CONFIGURATION
There are many other settings which specify how a particular distro's
services (archive and git) are provided. These should not normally be
.SH ACCESS CONFIGURATION
There are many other settings which specify how a particular distro's
services (archive and git) are provided. These should not normally be
When using this facility, it is important to always specify the
same suites in the same order:
When using this facility, it is important to always specify the
same suites in the same order:
-dgit will not be make a coherent fast-forwarding history
+dgit will not make a coherent fast-forwarding history
view otherwise.
The history generated by this feature is not normally suitable
view otherwise.
The history generated by this feature is not normally suitable
In the error message,
696c9bd5..84ae8f96
is the first commit child-parent edge
In the error message,
696c9bd5..84ae8f96
is the first commit child-parent edge
-which cannot be sensibly be
+which cannot sensibly be
either ignored, or turned into a patch in debian/patches.
In this example, this is because
it itself changes files in debian/patches,
either ignored, or turned into a patch in debian/patches.
In this example, this is because
it itself changes files in debian/patches,
For background, theory of operation,
and definitions see L<git-debrebase(5)>.
For background, theory of operation,
and definitions see L<git-debrebase(5)>.
-You should read this manpage in cojnunction with
+You should read this manpage in conjunction with
L<git-debrebase(5)/TERMINOLOGY>,
which defines many important terms used here.
L<git-debrebase(5)/TERMINOLOGY>,
which defines many important terms used here.
because git-rebase has a tendency to start the rebase
too far back in history,
and then drop important commits.
because git-rebase has a tendency to start the rebase
too far back in history,
and then drop important commits.
-Soo L<git-debrebase(5)/ILLEGAL OPERATIONS>
+See L<git-debrebase(5)/ILLEGAL OPERATIONS>
=item git-debrebase status
=item git-debrebase status
except for the laundering.
<new-version>
except for the laundering.
<new-version>
-may be whole new Debian version, including revision,
+may be a whole new Debian version, including revision,
or just the upstream part,
in which case -1 will be appended
to make the new Debian version.
or just the upstream part,
in which case -1 will be appended
to make the new Debian version.
are not a simple superset of those already in debian/patches,
make-patches will fail with exit status 7,
and an error message.
are not a simple superset of those already in debian/patches,
make-patches will fail with exit status 7,
and an error message.
-(The message can be suppress with --quiet-would-amend.)
+(The message can be suppressed with --quiet-would-amend.)
If the problem is simply that
the existing patches were not made by git-debrebase,
using dgit quilt-fixup instead should succeed.
If the problem is simply that
the existing patches were not made by git-debrebase,
using dgit quilt-fixup instead should succeed.
=item git-debrebase convert-from-gbp [<upstream-commit-ish>]
=item git-debrebase convert-from-gbp [<upstream-commit-ish>]
-Cnnverts any of the following into a git-debrebase interchange branch:
+Converts any of the following into a git-debrebase interchange branch:
This is provided mostly for the test suite
and for unusual situations.
This is provided mostly for the test suite
and for unusual situations.
-It should only be used with a care and
+It should be used only with care and
with a proper understanding of the underlying theory.
Be sure to not accidentally treat the result as
with a proper understanding of the underlying theory.
Be sure to not accidentally treat the result as
Directory to look in for orig tarballs.
The default is the git config option
dgit.default.build-products-dir
Directory to look in for orig tarballs.
The default is the git config option
dgit.default.build-products-dir
+or failing that, "C<..>".
Passed on to dgit, if git-debrebase invokes dgit.
=item --[no-]origs
Passed on to dgit, if git-debrebase invokes dgit.
=item --[no-]origs
git-debrebase has one primary branch,
the B<interchange branch>.
git-debrebase has one primary branch,
the B<interchange branch>.
-This branch is found on Debian contributor's workstations
+This branch is found on Debian contributors' workstations
(typically, a maintainer would call it B<master>),
in the Debian dgit git server as the suite branch (B<dgit/dgit/sid>)
and on other git servers which support Debian work
(typically, a maintainer would call it B<master>),
in the Debian dgit git server as the suite branch (B<dgit/dgit/sid>)
and on other git servers which support Debian work
The breakwater does not contain any representation of
the delta queue (not even debian/patches).
The part of the breakwater processed by git-debrebase
The breakwater does not contain any representation of
the delta queue (not even debian/patches).
The part of the breakwater processed by git-debrebase
-is the part since the most re
ecent B<anchor>,
+is the part since the most recent B<anchor>,
which is usually a special merge generated by git-debrebase.
When working, locally,
which is usually a special merge generated by git-debrebase.
When working, locally,
can later be
stitched into the fast-forwarding interchange form.
can later be
stitched into the fast-forwarding interchange form.
-An unstitched branch may be in
+An unstitched branch may be in the
B<laundered>
state,
which means it has a more particular special form
B<laundered>
state,
which means it has a more particular special form
=item Delta queue commits
Zero or more single-parent commits
=item Delta queue commits
Zero or more single-parent commits
-contaioning only changes to upstream files.
+containing only changes to upstream files.
It has the same contents as the laundered state,
except that it may contain,
additionally,
It has the same contents as the laundered state,
except that it may contain,
additionally,
-in B<in any order but after the breakwater>:
+B<in any order but after the breakwater>:
C<refs/debrebase-last/B> records some ancestor of refs/B,
(usually, the result of last stitch).
This is used for status printing and some error error checks -
C<refs/debrebase-last/B> records some ancestor of refs/B,
(usually, the result of last stitch).
This is used for status printing and some error error checks -
-especially for printing guesses what a problem is.
-To determine whether a branch is
+especially for printing guesses about what a problem is.
+To determine whether a branch
is being maintained in git-debrebase form
it is necessary to walk its history.
is being maintained in git-debrebase form
it is necessary to walk its history.
-The following basic operations follows from this model
+The following basic operations follow from this model
(refer to the diagram above):
=over
(refer to the diagram above):
=over
=item Stitch
Make a pseudomerge,
=item Stitch
Make a pseudomerge,
-whose contributing parent to is the unstitched branch
+whose contributing parent is the unstitched branch
and
whose overwritten parent is ffq-prev,
consuming ffq-prev in the process
and
whose overwritten parent is ffq-prev,
consuming ffq-prev in the process
=item Commit quilt patches
To generate a tree which can be represented as a
=item Commit quilt patches
To generate a tree which can be represented as a
-3.0 (quilt) .dsc source packages,
+3.0 (quilt) .dsc source package,
the delta queue must be reified inside the git tree
in B<debian/patches/>.
These patch files can be stripped out and/or regenerated as needed.
the delta queue must be reified inside the git tree
in B<debian/patches/>.
These patch files can be stripped out and/or regenerated as needed.
it is better to use git-debrebase and
let it choose the base
for your rebase.
it is better to use git-debrebase and
let it choose the base
for your rebase.
-If you do realise you have make this mistake,
+If you do realise you have made this mistake,
it is best to use the reflog to recover to a suitable
good previous state.
it is best to use the reflog to recover to a suitable
good previous state.
~ianmdlvl / dgit.git / commitdiff