Package: gitctl
ContentsChange history2.0a8 (2010-04-11)2.0a7 (2009-08-03)2.0a6 (2009-05-27)2.0a5 (2008-10-01)2.0a4 (2008-09-25)2.0a3 (2008-09-21)2.0a2 (2008-09-15)2.0a1 (2008-09-15)1.0b1 (2008-06-12)PurposeConfigurationgitctl.cfggitexternals.cfggitctlscriptInstallationExamplesgitctl pathgitctl shDependenciesContributorsGit clone URL: git://github.com/dokai/gitctl.gitProject page:http://github.com/dokai/gitctlChange history2.0a8 (2010-04-11)Bound GitPython dependency at version 0.1.7. gitctl is not compatible with
the newer versions. [dokai]Added experimental Growl support. You need to have the Growl python
bindings installed for it to work.2.0a7 (2009-08-03)Added a new –from-file option which tells to read the names of components
from a given file. The command then applies to the given components only.
[rnd]Added “gitctl path” command which prints path(s) to directories for given
component name(s). [rnd]Added “gitctl sh” command which performs specified shell commands (given
with -c option) in each component’s directory. E.g. gitctl sh -c ‘git
status’ will execute “git status” for each component. [rnd]2.0a6 (2009-05-27)Refactored the “gitctl pending” command to support only the comparison
between the pinned down revisions in the externals configuration and the
HEADs of the production branches. In practice this means the the former
–production switch is the default behavior and the –production, –staging
and –dev options have been removed. The refactored “gitctl status”
replaces the former functionality. [dokai]Refactored the “gitctl status” command to give more elaborate information
about the status of the repository. [dokai]Refactored the pretty printer to include a space between the component
name and the dotted justification. This will make it easier to use the
output of gitctl in other scripts. [dokai]Added a new –verbose global option. Providing the –verbose option will
give the same output as 2.0a5. Without the option the gitctl will only
report changed components which will reduce the output significantly and
make it easier to see what changed.Print normal program output to stdout and only errors to stderr. [dokai]When updating a hard-pinned revision perform a “git reset –hard” to enforce
the revision. This fixes some
issue where the working directory was in an inconsistent state and the
checkout failed. [dokai]Refactored thegenerate_externalsfunction to guarantee the order of
sections in the generated configuration file. [dokai]2.0a5 (2008-10-01)Changed ‘gitctl update’ to attempt a fast-forward merge on all configured
branches. If fast-forward is not possible a message will be shown and the
branch left unchanged. [dokai]2.0a4 (2008-09-25)Fixed ‘gitctl pending –production’ which compared the wrong trees. When
using pinned down revisions (HEADless working directories) we need to
always compare against the remote branches. [dokai]Fixed a bug in ‘gitctl pending’ if not all branches were available. [dokai]Added the ‘-v’ switch to show the version of the gitctl. [dokai]2.0a3 (2008-09-21)Added support for specifying the initial commit message by using
‘gitctl create –message’. [dokai]Fixed ‘gitctl create’ to not leave the upstream repository’s HEAD in broken
state. [dokai]Added support for specifying which projects to operate on in addition to
performing an operation on all the projects in the externals
configuration. [dokai]Added a –no-fetch option to ‘gitctl pending’ to avoid fetching. [dokai]‘gitctl update’ now shows which projects were updated and which were not
when using pinned down revisions [dokai]2.0a2 (2008-09-15)Fixed a critical bug with ‘gitctl update’ when using pinned down revisions.
[dokai]2.0a1 (2008-09-15)Complete overhaul to implement (a particular) Git workflow process in
addition to custom externals handling. This breaks backward compatibility
with the 1.x version but provides somewhat equivalent functionality.
[dokai]1.0b1 (2008-06-12)Initial public release [dokai]PurposeThe purpose of this package is to implement a particular workflow for using
Git to manage a project that consists of multiple independent subprojects. The
original motivation is a zc.buildout driven system, but the implementation is
not dependent on this. This is not a 100% generic tool, but the workflow is
fairly common so it may be adaptable for other use cases also.The workflow consists of using three pre-defined branches to model thedevelopment,stagingandproductionphases of code. We assume the
use of a canonical central repository that developers use to sync their
official changes. This repository is considered to be the canonical source and
provides the “official” state of the projects. Developers are free to use any
number of branches, tags and repositories as part of their daily work.The code normally flows fromdevelopmenttostagingtoproductionand the package provides tools to facilitate this process. Each individual Git
repository is managed using any of the tools that Git provides.In addition, the package provides a light-weight “externals” mechanism for
easily pulling in and managing the subprojects. This differs from the
functionality provided bygit-submodulein that both pinned-down and open
dependencies can be defined. This resembles the way externals are handled in
Subversion. Also, the individual Git repositories are not aware of the
externals and the externals configuration is kept in a single location.ConfigurationThe package uses two different configuration files. Thegitctl.cfgfile
provides the higher level configuration and allows you to specify things like
the canonical repository and the names of yourdevelopment,stagingandproductionbranches. Thegitexternals.cfgdefines your project
specific configuration of required sub-components.gitctl.cfgupstreamThe name used to refer to the canonical repository server, e.g. “origin”.upstream-urlThe address of the canonical repository server. This address needs to
point to the server in a manner that supports pushing. Currently only SSH
is tested. Example:git@my.gitserver.combranchesList of newline separated branches that will be tracked in the local
repository. When the repositories are clone for each branch listed here a
local tracking branch will be automatically created.development-branchName of the development branch. The abovebrancheslisting will be
made to implicitly contain this branch.staging-branchName of the staging branch. The abovebrancheslisting will be made to
implicitly contain this branch.production-branchName of the production branch. The abovebrancheslisting will be made
to implicitly contain this branch.commit-emailEmail address where commit emails will be sent. Only used when creating
new repositories.commit-email-prefixThe commit email prefix. Only used when creating new repositories.An example configuration follows:[gitctl]
upstream = origin
upstream-url = git@myserver.com
branches =
    development
    staging
    production
development-branch = development
staging-branch = staging
production-branch = production
commit-email = commit@myserver.com
commit-email-prefix = [GIT]gitexternals.cfgThe externals configuration consists of one or more sections that have the
following properties. Each section name will be used to name the directory
where the external will be cloned into.url(mandatory)Full URL to the remote repository, e.ggit@myserver.com:my.project.gittype(optional)The type of the remote repository. Currently onlygitis supported.treeish(optional)The name of a “treeish” object that is checked out by default when first
cloning the remote repository. The treeish object may refer, for example,
to a branch or a tag. Defaults tomaster.container(optional)The name of the directory where the project will be checked out
into. An additional directory will be created under this one where
the project files will be located so it is safe to use the same
value for multiple projects. Relative paths are considered
relative to the location of the config file.An example configuration follows:[my.project]
url = git@myserver.com:my.project.git
type = git
treeish = v1.0-dev
container = srcThis results in the my.project.git repository to be cloned into
./src/my.project and the v1.0-dev to be checked out into the working
directory.gitctlscriptThegitctlscript provides subcommands to implement the workflow. Each
subcommand provides additional options. Seegitctl [subcommand]--helpfor
details:usage: gitctl [-h] [-v] [--config CONFIG] [--externals EXTERNALS] [--verbose]
              {status,create,update,sh,branch,path,fetch,pending} ...

Git workflow utility for managing projects containing multiple git
repositories.

positional arguments:
  {status,create,update,sh,branch,path,fetch,pending}
                        Commands
    create              Initializes a new local repository and creates a
                        matching upstream repository.
    update              Updates the configured repositories by either
                        attempting a fast-forward merge on existing project
                        branches or cloning new projects.
    path                Shows the path to the project directory.
    sh                  Executes shell command for specified projects.
    status              Shows the status of each external project and alerts
                        if any are out of sync with the upstream repository.
    branch              Provides information and operates on the branches of
                        the projects.
    pending             Checks if there are any pending changes in the
                        production branches compared to the pinned down
                        versions in externals configuration.
    fetch               Updates the remote branches on all projects without
                        merging.

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  --config CONFIG       Location of the configuration file. If omitted the
                        following locations will be search: $PWD/gitctl.cfg,
                        ~/.gitctl.cfg.
  --externals EXTERNALS
                        Location of the externals configuration file. Defaults
                        to $PWD/gitexternals.cfg
  --verbose             Prints more verbose output about repositories.InstallationUsing setuptools:$ easy_install gitctlExamplesgitctl pathOutputs the path(s) of the project directories:$ cd /Users/rnd/buildout/
$ gitctl path -f refactoring_these_projects
/Users/rnd/buildout/products/Project1
/Users/rnd/buildout/products/Project2
/Users/rnd/buildout/src/Project3where therefactoring_these_projectsfile contains project names,
one per line:ProjectI
ProjectII
ProjectIIIThese project names map to the sections in thegitexternals.cfgconfiguration.Without providing project names, all project paths will be output.gitctl shExecutes shell command in each project directory (that is, the
directory with pathgitctl pathshows). Some examples (using the
same filerefactoring_these_projectsas above).Show branches for each project (PROJECTenvironment variable holds
the name of the project):gitctl sh -f refactoring_these_projects -c 'echo $PROJECT; git branch'Making feature branch:gitctl sh -f refactoring_these_projects -c 'git checkout -b my_f_branch'Mass-check out certain feature branch (first, all projects to development,
then checkout feature branch only for projects under refacture):gitctl sh -c 'git checkout development'
gitctl sh -f refactoring_these_projects -c 'git checkout my_f_branch'Get a list of projects which have production different from
development (N.B. checked via commit, not diff, so, some listed
project may really be textually identical):gitctl sh -f refactoring_these_projects -c '[ `git rev-parse development` != `git rev-parse origin/production` ] && echo $PROJECT' 2> /dev/nullMake some operations on selected projects:gitctl sh -f refactoring_these_projects -c 'git commit -m "Added newfeature"'DependenciesGit>= 1.6argparseGitPython== 0.1.7ContributorsKai Lautaportti, Author [dokai]Roman Susi, [rnd]