go-utils/sunrise-commit.1.in

.TH SUNRISE-COMMIT 1 "13 Jul 2010" "@PACKAGE_STRING@" "User Commands"

.SH NAME

sunrise-commit \- a Gentoo repository commit helper.

.SH SYNOPSIS

.B sunrise-commit
[options]
[--]
.I <commit-message>

.SH DESCRIPTION

.B sunrise-commit
is a helper script for Gentoo repository commiters. Apart from
performing the actual commit, it performs the following tasks:

\- performs basic integrity and QA checks on the modified packages,

\- handles ChangeLog and Manifest updates,

\- prepends the commit message with package name(s).

The script supports CVS, GIT, Mercurial, and Subversion repositories.
For the latter, it supports native checkouts as well as git-svn.

Please note that when used with DVCSes, this script only performs the
actual commit. (It does not push or dcommit it to the repository).
However, native Subversion and CVS commits are sent directly to the remote
repository (due to limitations of non-distributed VCSes).

.SH OPTIONS

.IP "\fB-c\fP, \fB--changelog\fP"

Ignored (provided for backwards compatibility). ChangeLog entries are
now created as needed. Use \fB--trivial\fP to suppress creation of
ChangeLog entries.

Because of the nature of DVCSes, a ChangeLog will not be created for a
new ebuild in a GIT or Mercurial repository. However, if the ebuild
already has a ChangeLog file, it will be updated. One consideration is
that if a ChangeLog file is maintained and the repository needs to be
merged after two people adjust the same ebuild, the ChangeLog will
cause merge conflicts. Also, viewing a DVCS's log does not require an
Internet connection.

.IP "\fB-C\fP, \fB--nocolor\fP"

Disable colorful output (for terminals which do not support escape
sequences).

.IP "\fB-d\fP, \fB--noupdate\fP"

Do not update and rebase the repository before proceeding with the
commit. This option only applies to Subversion and CVS repositories.
It makes no sense to automatically pull from remote DVCS repositories.

.IP "\fB-f\fP, \fB--force\fP"

Force proceeding with the commit even if QA violations occur. With
this option, errors from `\fIrepoman full\fP' will be ignored and
\fB--force\fP is passed to `\fIrepoman commit\fP'.

.IP "\fB-m\fP, \fB--noformat\fP"

Do not prepend the commit message with package names.

.IP "\fB-q\fP, \fB--quiet\fP"

Ignored (provided for backwards compatibility).

.IP "\fB-t\fP, \fB--trivial\fP"

Assume the changes are trivial and thus do not require a ChangeLog
entry. Examples of trivial changes include updating Manifests and
minor correction of previous ChangeLog entries.

.IP "\fB-v\fP, \fB--verbose\fP"

Enable verbose output. Useful mostly for debugging.

.IP "\fB-?\fP, \fB-h\fP, \fB--help\fP"

Print a short help message and exit.

.IP "\fB-V\fP, \fB--version\fP"

Print the version string and exit.

.SH ENVIRONMENT

.IP ECHANGELOG_USER

the committer name and e-mail as it would appear in ChangeLog.
The sunrise-suggested format is:

.IR "Real Name" " (" nickname ") <" e-mail >

`\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
native Subversion repository and that the initial working directory is
the branch's or repository's root.

.I "1. Adding a new ebuild:"

.nf
$ svn mkdir app-foo/bar
$ cd app-foo/bar
[...]
$ svn add bar-1.ebuild
$ sunrise-commit 'New ebuild for bug #nnnnnn.'
.fi

.I "2. Performing a version bump:"

.nf
$ cd app-foo/bar
$ svn mv bar-1.ebuild bar-2.ebuild
[...]
$ sunrise-commit 'Version bump.'
.fi

.I "3. Fixing a broken Manifest:"

.nf
$ cd app-foo/bar
$ sunrise-commit -t 'Fixing a broken Manifest.'
.fi

(\fB sunrise-commit\fP always updates the Manifest)

.I "4. Removing a package which was added to gx86:"

.nf
$ svn rm app-foo/bar
$ sunrise-commit -f 'in gx86.'
.fi

.SH "REPORTING BUGS"

Please report bugs via Gentoo Bugzilla:

.I http://bugs.gentoo.org/

.SH AUTHORS

Michal Gorny <gentoo@mgorny.alt.pl>

Nathan Phillip Brink <ohnobinki@ohnopublishing.net>

.SH "SEE ALSO"

.BR ebuild (5),
.BR echangelog (1),
.BR cvs (1),
.BR git (1),
.BR hg (1),
.BR repoman (1),
.BR svn (1)