Metadata-Version: 1.1
Name: git-change
Version: 0.1.0
Summary: Git command to create and manage Gerrit Code Review changes
Home-page: https://github.com/Nextdoor/git-change
Author: Jacob Hesch
Author-email: jacob@nextdoor.com
License: Apache License, Version 2.0
Description: ============
         git-change
        ============
        
        `Git-change` is a Git command which creates and manages changes for
        the `Gerrit Code Review`_ tool.
        
        The goal of `git-change` is to simplify the interface for creating and
        managing code reviews in Gerrit and make that process feel like a
        natural extension of Git.
        
        Aside from providing some syntactic sugar for dealing with Gerrit code
        reviews in the form of a Git command, the primary feature `git-change`
        adds is branch management for changes. `git-change` creates a
        temporary, local branch (a *change branch*) for each change, allowing
        you to have several code reviews in flight without introducting
        dependencies between them. For example, let's say you've made two
        changes, A followed by B, and sent them both out for code reviews. If
        the reviewer of change B responds with thumbs up before A's reviewer
        does, you can go ahead and submit B and Gerrit will merge it right
        away. Without separate branches, Gerrit would refuse to submit B until
        A has been approved and submitted. Because `git-change` creates a
        separate branch for each change, they are independent, allowing Gerrit
        to merge them out of order into the same target branch (e.g.,
        *master*). Of course, sometimes you *want* B to depend on A and you
        can do that, too, by passing the ``--chain`` flag to ``git change``.
        
        `Git-change` is written in Python.
        
        
        Installation
        ------------
        
        To install, run ::
        
            pip install git-change
        
        You can also download the latest release directly from the `Python
        Package Index`_ or clone the `GitHub repository`_ and install with
        ``python setup.py install``.
        
        
        Setup
        -----
        
        Configure Gerrit SSH host
        ~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Add an entry to your SSH config file for your Gerrit server. Place the
        following lines in ``~/.ssh/config``, substituting the details
        according to your system: ::
        
            Host review
                Hostname review.example.com
                Port 29418
                User tyrion
        
        Set ``git-config`` options
        ~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Add an entry to your repository's Git config file for the Gerrit SSH
        host above. Add an entry for your remote (note that this is necessary
        only if the remote is named something other than "origin"). You can
        add the entries by running the following commands, substituting the
        details according to your system: ::
        
            git config git-change.remote <remote-name>
            git config git-change.gerrit-ssh-host <gerrit-ssh-host>
        
        Install Git hooks
        ~~~~~~~~~~~~~~~~~
        
        `Git-change` requires that you install the ``commit-msg`` hook that
        ships with Gerrit. The hook ensures that every commit has a
        ``Change-Id`` header in its commit message. Assuming you configured
        the Gerrit SSH host above with the name ``review``, and that the
        current working directory is the root of your local Git repository,
        run the following command to install the hook: ::
        
            scp -p review:hooks/commit-msg .git/hooks/
        
        If you want `git-change` to inject bug IDs to your commit messages via
        the ``--bug`` option, install the ``prepare-commit-msg`` hook script
        by copying the file from the ``extras`` directory of the `git-change`
        source distribution to your repository's ``.git/hooks`` directory.
        
        
        Workflow
        --------
        
        After hacking together a killer feature, stage the changed files and
        send to Gerrit for review: ::
        
            git add .
            git change create --reviewers=arya
        
        This commits the staged changes to a temporary, local *change*
        *branch*. The tracking branch you started from (``master``, for
        example) is left in the state it was in before the changes, which
        means that you can now start on another change that does not depend on
        the first change.
        
        Note that ``create`` is the default subcommand and can be omitted. So
        ``git change --reviewers=arya`` does exactly the same thing as
        the command above.
        
        The change branch created by `git-change` includes the Change ID
        generated by the Gerrit ``commit-msg`` hook. It looks something like
        ``change-I5372aa17af2c0ddc0de4c15688c605a0e668caa0``.
        
        After the reviewer has responded to your code review with feedback and
        you've made the requested changes, switch to the change branch and use
        ``git change update`` to push the changes as a new patch set: ::
        
            git change list
            git add .
            git change update
        
        ``git change list`` lists all your change branches and as a
        convenience it provides a menu to select the one you want to switch
        to. You can also just switch using ``git checkout``. After you stage
        your changes, running ``git change update`` adds the staged changes to
        the current HEAD commit (by running ``git commit --amend`` behind the
        scenes) and pushes a new patch set to Gerrit.
        
        When it comes time to submit you can either use the Gerrit web
        interface, or you can run ::
        
            git change submit
        
        If one or more of the files in your change was updated by someone else
        in the remote branch meanwhile, Gerrit will refuse to submit the
        change. Usually in this case you need to pull the upstream changes
        into your local tracking branch and from there rebase them into your
        change branch, then finally push them back up to Gerrit as part of
        your change. The ``rebase`` subcommand handles all of this for you in
        one step: ::
        
            git change rebase
        
        Sometimes the rebase operation fails due to merge conflicts. If this
        happens, resolve the conflicts and run ``git change rebase``
        again. See git-rebase(1) for more information about how to proceed
        after resolving conflicts.
        
        Finally, a word on housekeeping. Any change branches that accumulate
        can be cleared out once the corresponding upstream commits have been
        pulled into your local tracking branch by running ::
        
            git change gc
        
        Note that only change branches that were created from the *current*
        tracking branch will be removed. If the current branch is ``master``
        but you have old change branches created from the ``feature`` branch,
        you have to switch to ``feature`` before running ``git change gc`` in
        order to clear out those branches. Of course, you can also remove
        stale change branches "manually" with ``git branch -d <branch>``.
        
        
        Documentation
        -------------
        
        For the full documentation see the ``git-change.rst`` file or the man
        page, ``git-change(1)``.
        
        
        Extras
        ------
        
        The ``extras`` directory of the source distribution contains the
        following extras:
        
        Bash completion
        ~~~~~~~~~~~~~~~
        
        This package includes a Bash completion script that completes command
        line option names and values. It depends on the completion script that
        ships with Git. On Debian/Ubuntu systems, the ``git`` package installs
        that script as ``/etc/bash_completion.d/git``.
        
        Add the following lines to your Bash init file (e.g., ``~/.bashrc``),
        adjusting the paths as necessary for your system: ::
        
            source /etc/bash_completion.d/git
            source extras/bash_completion.d/git-change
        
        If you use `virtualenv`_, you can source the `git-change` completion
        script as follows: ::
        
            source $VIRTUAL_ENV/etc/bash_completion.d/git-change
        
        You can also define a list of reviewers in your organization so that
        their names appear as completion candidates for options like
        ``--reviewers`` and ``--cc``. Place the list of reviewers according to
        their Gerrit user names in a text file, one per line. Then add this
        line to your Bash init file, adjusting the path as necessary: ::
        
            export GIT_CHANGE_REVIEWERS_FILE=/path/to/file
        
        This works for relatively small lists of reviewers, but probably does
        not scale well for large organizations.
        
        Hooks
        ~~~~~
        
        This package includes a ``prepare-commit-msg`` Git hook script which
        injects a ``Bug`` header into commit messages if the ``BUG_ID``
        environment variable is set. ``git-commit create`` sets ``BUG_ID`` if
        you pass it the ``--bug`` option.
        
        
        Bugs
        ----
        
        Please report bugs on the GitHub `issues page`_.
        
        
        Contributing
        ------------
        
        To contribute, clone the `GitHub repository`_ and initiate a pull
        request with your changes.
        
        
        See also
        --------
        
        The folks at OpenStack_ maintain a similar tool called `git-review`_.
        
        
        .. _Gerrit Code Review: http://code.google.com/p/gerrit/
        .. _Python Package Index: http://pypi.python.org/pypi/git-change
        .. _issues page: https://github.com/Nextdoor/git-change/issues
        .. _GitHub repository: https://github.com/Nextdoor/git-change
        .. _virtualenv: http://www.virtualenv.org/
        .. _OpenStack: http://openstack.org/
        .. _git-review: https://github.com/openstack-ci/git-review
        .. _Nextdoor: http://www.nextdoor.com/
        
Keywords: gerrit git code review
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Topic :: Software Development
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Operating System :: POSIX
Classifier: Natural Language :: English
