From b0ec712f3354ca9d73e6a963465ffa0ebb02a427 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= Date: Sat, 30 Oct 2010 21:28:35 +0200 Subject: [PATCH] Add detailed scenario descriptions. --- sunrise-commit.1.in | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/sunrise-commit.1.in b/sunrise-commit.1.in index 1c54045..f9c4e58 100644 --- a/sunrise-commit.1.in +++ b/sunrise-commit.1.in @@ -101,6 +101,50 @@ The sunrise-suggested format is: `\fInickname\fP' corresponds to the committer's IRC nickname. +.SH "EXTENDED DESCRIPTION" + +.IP "Adding packages" + +The primary use of sunrise-commit is to commit packages to a repository. +In order to use it in this scenario, you are expected to run it from +within the package directory (one with the ebuilds), providing +an appropriate changelog message. + +If your package requires an additional file to be committed outside +the package directory (e.g. an eclass, a license) you need to commit it +manually \fBbefore\fP using sunrise-commit. + +What sunrise-commit will do for you is the ChangeLog entry and calling +repoman to do the actual commit. If you think your commit doesn't +deserve a ChangeLog entry, use \fB--trivial\fP. + +If you're adding a new package, it may be also necessary to use +\fB--noupdate\fP to avoid calling VCS update command as it could fail +with a freshly created directory (especially with subversion). + +.IP "Removing packages" + +sunrise-commit can be used to remove a set of packages too. In order to +do so, first mark all the expected packages removed using your VCS. +Perform the necessary \fBpackage.mask\fP changes too, and remove +licenses no longer in use. + +Afterwards, call \fBsunrise-commit\fP from within your repository root +directory, passing the removal reason. The script will prepend it with +the complete removed package list. + +Please notice that it will commit all changes in \fBeclass\fP, +\fBlicenses\fP and \fBprofiles\fP directories too. This is in order to +accomodate the need of removing \fBpackage.mask\fP entries and unused +files but could cause trouble if the working copy is dirty. + +sunrise-commit will check whether the removed package is not referenced +by any of the other packages by default. This is in order to ensure that +no package will be left with unsatisfied dependencies. However, if +you're removing the package because it was moved to a master repository +(e.g. gx86), you may want to pass \fB--force\fP in order to ignore that +check. + .SH EXAMPLES All of the following examples assume that the committer is using a