From 0204be1f752d1d165074aab2aaf315c721ce4cd0 Mon Sep 17 00:00:00 2001 From: Guido Guenther Date: Sun, 7 Oct 2007 15:31:25 +0200 Subject: add some basic documentation for git-dch --- docs/chapters/chapters.ent | 1 + docs/chapters/intro.sgml | 3 ++ docs/chapters/releases.sgml | 62 +++++++++++++++++++++++++++++++++++++ docs/chapters/special.sgml | 2 +- docs/common.ent | 1 + docs/manpages/git-buildpackage.sgml | 2 +- docs/manpages/git-dch.sgml | 61 +++++++++++++++++++++++++++++++----- docs/manpages/git-import-dsc.sgml | 2 +- docs/manpages/git-import-orig.sgml | 2 +- docs/manual.sgml | 1 + 10 files changed, 126 insertions(+), 11 deletions(-) create mode 100644 docs/chapters/releases.sgml diff --git a/docs/chapters/chapters.ent b/docs/chapters/chapters.ent index 68fea426..fd7c6da3 100644 --- a/docs/chapters/chapters.ent +++ b/docs/chapters/chapters.ent @@ -2,5 +2,6 @@ + diff --git a/docs/chapters/intro.sgml b/docs/chapters/intro.sgml index 4097793d..683811e9 100644 --- a/docs/chapters/intro.sgml +++ b/docs/chapters/intro.sgml @@ -35,6 +35,9 @@ always build the package with &git-buildpackage;. In case you have uncommitted changes in your source tree you can use the option. + Optionally you can create the Debian changelog entries + using &git-dch; and create snapshot releases for testing using the + option. Once satisfied you can build the final package with &git-buildpackage; . This additionally creates a tag within &git; so you can switch back to that diff --git a/docs/chapters/releases.sgml b/docs/chapters/releases.sgml new file mode 100644 index 00000000..58ac40f9 --- /dev/null +++ b/docs/chapters/releases.sgml @@ -0,0 +1,62 @@ + + Releases and Snapshots + When branching and merging frequently, the different Debian changelog + entries on the different branches tend to get into the way of the automatic + merge and the the merge fails - leaving the (patholigical) merge to the + committer. In order to avoid this &git-dch; offers a way for creating + changelog entries from &git; commits before doing a + release or anytime between releases. + + The simplest way is doing all the changes to the + debian-branch without touching + debian/changelog at all. Then, when done, do: + + +&git-dch; --release + + This will look up the latest released version in the changelog, + increment the version in the &debian; changelog, generate changelog + messages from the corresponding &git; commit id up to the branch head and + finally spawns an editor for final changelog file editing by invoking &dch; + . + + But what if you want to have an (unreleased) snapshot for intermediate testing: + +&git-dch; --snapshot + + will generate a snapshot release with a specially crafted version number + and a warning in the changelog that this is a snapshort release: + + +git-buildpackage (0.3.7~1.gbp470ce2) UNRELEASED; urgency=low + + ** SNAPSHOT build @470ce29ec7877705c844474a2fd89869aea0406d ** + + * add support for automatic snapshot + + During subsequent calls with this version + number will continue to increase. Since the snapshot banners contains the + commit id of the current branch head, &git-dch; can figure out what to + append to the changelog by itself: + +&git-dch; --snapshot --auto + + will fetch the commit id and add changelog entries from that point to the + current HEAD - again auto incrementing the version number. If you don't want + to start at that commit id, you can specify any id or tag with: + +&git-dch; --since=e76a6a180a57701ae4ae381f74523cacb3152780 --snapshot + + + After testing you can remove the snapshot header by a final &git-dch; call: + + +&git-dch; --since=HEAD --release + + + This will add no further entries but simply remove the specially crafted + version number and the snapshort header. Again you can use any commit id + or tag instead of if you want to add further changelog + entries - or you can (of course) use again. + + diff --git a/docs/chapters/special.sgml b/docs/chapters/special.sgml index 3ac7a80f..e63da062 100644 --- a/docs/chapters/special.sgml +++ b/docs/chapters/special.sgml @@ -1,4 +1,4 @@ - + Special usage cases Handling non-DFSG clean upstream sources diff --git a/docs/common.ent b/docs/common.ent index 31e9835a..c2f26502 100644 --- a/docs/common.ent +++ b/docs/common.ent @@ -16,6 +16,7 @@ Debian"> Git"> + dch"> Pbuilder"> Git_load_dirs"> Debuild"> diff --git a/docs/manpages/git-buildpackage.sgml b/docs/manpages/git-buildpackage.sgml index 00c9b856..e1803ca8 100644 --- a/docs/manpages/git-buildpackage.sgml +++ b/docs/manpages/git-buildpackage.sgml @@ -163,7 +163,7 @@ SEE ALSO - git-import-dsc (1), git-import-orig (1), debuild (1), git (1) + git-import-dsc (1), git-import-orig (1), debuild (1), git (1), git-dch (1) diff --git a/docs/manpages/git-dch.sgml b/docs/manpages/git-dch.sgml index ed0d99e1..9b058bb7 100644 --- a/docs/manpages/git-dch.sgml +++ b/docs/manpages/git-dch.sgml @@ -15,7 +15,7 @@ &git-dch; - Generate Debian changelog from git commit messages + Generate the Debian changelog from git commit messages @@ -25,19 +25,36 @@ branch_name tag-format commitish + + + + git-log-options + [path1 path2] DESCRIPTION - &git-dch; reads git commit messages and generates the debian changelog from it. If no arguments - are given &git-dch; starts from the last tagged debian package version up - to the current tip of the debian-branch. If the + &git-dch; reads git commit messages and generates the debian changelog from + it. If no arguments are given &git-dch; starts from the last tagged debian + package version up to the current tip of the current branch. If the distribution of the topmost section in debian/changelog is UNRELEASED the changelog entries will be inserted into this section. Otherwise a new - section is being created. - + section will be created. + If is given &git-dch; tries to guess the + last &git; commit documented in the changelog - this only works in snapshot + mode. Otherwise can be used to tell &git-dch; + at which point it should start in the &git; history. + + The additional path arguments can be used to restrict the repository paths + &git-dch; looks at. Setting path to + debian/ is a good choice if upstream uses &git; and + all Debian packaging changes are restricted to the + debian/ subdir. In more sophisticated cases + (like backports) you can use to restrict the + generated changelog entries further. E.g. by using + "--author=Foo Bar". OPTIONS @@ -72,6 +89,36 @@ start reading commit messages at committish + + + + Guess the last commit documented in the changelog from the + snapshot banner (or from the last tag if no snapshot banner exists). + + + + + + create a snapshot release entry. This adds a snapshot release + number and a warning banner to the changelog entry. The release + version number is being autoincremented with every new snapshot + release to avoid packages downgrades during snapshot testing. + + + + + + Remove any snapshot release banners and version suffixes, set + the current distribution to unstable and + open the changelog for final tweaking. + + + git-log-options + + + options passed on verbatim to git-log(1) + + @@ -80,7 +127,7 @@ SEE ALSO - git-buildpackage (1), git-import-dsc (1), git (1), git_load_dirs (1) + git-buildpackage (1), git-import-dsc (1), git-import-orig (1), git (1), git_load_dirs (1) diff --git a/docs/manpages/git-import-dsc.sgml b/docs/manpages/git-import-dsc.sgml index 5f4e5d45..38940f76 100644 --- a/docs/manpages/git-import-dsc.sgml +++ b/docs/manpages/git-import-dsc.sgml @@ -111,7 +111,7 @@ SEE ALSO - git-buildpackage (1), git-import-orig (1), git (1), git_load_dirs (1) + git-buildpackage (1), git-import-orig (1), git (1), git_load_dirs (1), git-dch (1) AUTHOR diff --git a/docs/manpages/git-import-orig.sgml b/docs/manpages/git-import-orig.sgml index 8553561c..a8900ddb 100644 --- a/docs/manpages/git-import-orig.sgml +++ b/docs/manpages/git-import-orig.sgml @@ -129,7 +129,7 @@ SEE ALSO - git-buildpackage (1), git-import-dsc (1), git (1), git_load_dirs (1) + git-buildpackage (1), git-import-dsc (1), git (1), git_load_dirs (1), git-dch (1) diff --git a/docs/manual.sgml b/docs/manual.sgml index 246e6070..6d188fdc 100644 --- a/docs/manual.sgml +++ b/docs/manual.sgml @@ -20,6 +20,7 @@ &ch.intro; &ch.import; &ch.building; + &ch.releases; &ch.cfgfile; &ch.special; -- cgit v1.2.3