git-debpush: Check upstream source is identical in the upstream tag

[dgit.git] / dgit-maint-merge.7.pod

diff --git a/dgit-maint-merge.7.pod b/dgit-maint-merge.7.pod
index a02e1fd757023f6d2ae10d855fb9537cca74e6e4..0ccd8c7e7fd6f5885e5c471ec75f3a7c429b3f50 100644 (file)
--- a/dgit-maint-merge.7.pod
+++ b/dgit-maint-merge.7.pod
@@ -68,12 +68,12 @@ been tagged '1.2.2' by upstream.
 The final command detaches your master branch from the upstream remote,
 so that git doesn't try to push anything there, or merge unreleased
 upstream commits.  If you want to maintain a copy of your packaging
-branch on B<alioth.debian.org> in addition to B<dgit-repos>, you can
+branch on B<salsa.debian.org> in addition to B<dgit-repos>, you can
 do something like this:
 
 =over 4
 
-    % git remote add -f origin git.debian.org:/git/collab-maint/foo.git
+    % git remote add -f origin salsa.debian.org:Debian/foo.git
     % git push --follow-tags -u origin master
 
 =back
@@ -120,6 +120,32 @@ upstream's tarball instead of running git-deborig(1).
 
 =back
 
+=head3 Using untagged upstream commits
+
+=over 4
+
+Sometimes upstream does not tag their releases, or you want to package
+an unreleased git snapshot.  In such a case you can create your own
+upstream release tag, of the form B<upstream/>I<ver>, where I<ver> is
+the upstream version you plan to put in I<debian/changelog>.  The
+B<upstream/> prefix ensures that your tag will not clash with any tags
+upstream later creates.
+
+For example, suppose that the latest upstream release is 1.2.2 and you
+want to package git commit ab34c21 which was made on 2013-12-11.  A
+common convention is to use the upstream version number
+1.2.2+git20131211.ab34c21 and so you could use
+
+=over 4
+
+    % git tag -s upstream/1.2.2+git20131211.ab34c21 ab34c21
+
+=back
+
+to obtain a release tag, and then proceed as above.
+
+=back
+
 =head2 When upstream releases only tarballs
 
 We need a virtual upstream branch with virtual release tags.
@@ -173,11 +199,11 @@ Then we can import the upstream version:
 
 Our upstream branch cannot be pushed to B<dgit-repos>, but since we
 will need it whenever we import a new upstream version, we must push
-it somewhere.  The usual choice is B<alioth.debian.org>:
+it somewhere.  The usual choice is B<salsa.debian.org>:
 
 =over 4
 
-    % git remote add -f origin git.debian.org:/git/collab-maint/foo.git
+    % git remote add -f origin salsa.debian.org:Debian/foo.git
     % git push --follow-tags -u origin master upstream
 
 =back
@@ -311,11 +337,11 @@ important information present in README.source.
 
 =head1 BUILDING AND UPLOADING
 
-Use B<dgit build>, B<dgit sbuild>, B<dgit build-source>, and B<dgit
-push> as detailed in dgit(1).  If any command fails, dgit will provide
-a carefully-worded error message explaining what you should do.  If
-it's not clear, file a bug against dgit.  Remember to pass I<--new>
-for the first upload.
+Use B<dgit build>, B<dgit sbuild>, B<dgit pbuilder>, B<dgit
+cowbuilder>, B<dgit push-source>, and B<dgit push> as detailed in
+dgit(1).  If any command fails, dgit will provide a carefully-worded
+error message explaining what you should do.  If it's not clear, file
+a bug against dgit.  Remember to pass I<--new> for the first upload.
 
 As an alternative to B<dgit build> and friends, you can use a tool
 like gitpkg(1).  This works because like dgit, gitpkg(1) enforces that
@@ -340,11 +366,15 @@ to git), you can just run dpkg-buildpackage(1) or debuild(1) instead.
 
 =back
 
+If you want to package an untagged upstream commit (because upstream
+does not tag releases or because you want to package an upstream
+development snapshot), see "Using untagged upstream commits" above.
+
 =head3 When upstream releases only tarballs
 
 You will need the I<debian/gbp.conf> from "When upstream releases only
 tarballs", above.  You will also need your upstream branch.  Above, we
-pushed this to B<alioth.debian.org>.  You will need to clone or fetch
+pushed this to B<salsa.debian.org>.  You will need to clone or fetch
 from there, instead of relying on B<dgit clone>/B<dgit fetch> alone.
 
 Then, either
@@ -371,7 +401,7 @@ accounting for in your copyright file:
 
 =over 4
 
-    % git diff --stat master..1.2.3 -- . ':!debian'
+    % git diff --name-status --diff-filter=ADR master..1.2.3 -- . ':!debian'
 
 =back