{
    "info": {
        "author": "Jacob Hesch",
        "author_email": "jacob@nextdoor.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 4 - Beta",
            "Intended Audience :: Developers",
            "License :: OSI Approved :: Apache Software License",
            "Natural Language :: English",
            "Operating System :: POSIX",
            "Programming Language :: Python :: 2",
            "Topic :: Software Development"
        ],
        "description": "============\n git-change\n============\n\n`Git-change` is a Git command which creates and manages changes for\nthe `Gerrit Code Review`_ tool.\n\nThe goal of `git-change` is to simplify the interface for creating and\nmanaging code reviews in Gerrit and make that process feel like a\nnatural extension of Git.\n\nAside from providing some syntactic sugar for dealing with Gerrit code\nreviews in the form of a Git command, the primary feature `git-change`\nadds is branch management for changes. `git-change` creates a\ntemporary, local branch (a *change branch*) for each change, allowing\nyou to have several code reviews in flight without introducting\ndependencies between them. For example, let's say you've made two\nchanges, A followed by B, and sent them both out for code reviews. If\nthe reviewer of change B responds with thumbs up before A's reviewer\ndoes, you can go ahead and submit B and Gerrit will merge it right\naway. Without separate branches, Gerrit would refuse to submit B until\nA has been approved and submitted. Because `git-change` creates a\nseparate branch for each change, they are independent, allowing Gerrit\nto merge them out of order into the same target branch (e.g.,\n*master*). Of course, sometimes you *want* B to depend on A and you\ncan do that, too, by passing the ``--chain`` flag to ``git change``.\n\n`Git-change` is written in Python.\n\n\nInstallation\n------------\n\nTo install, run ::\n\n    pip install git-change\n\nYou can also download the latest release directly from the `Python\nPackage Index`_ or clone the `GitHub mirror`_ and install with\n``python setup.py install``.\n\n\nSetup\n-----\n\nConfigure Gerrit SSH host\n~~~~~~~~~~~~~~~~~~~~~~~~~\n\nAdd an entry to your SSH config file for your Gerrit server. Place the\nfollowing lines in ``~/.ssh/config``, substituting the details\naccording to your system: ::\n\n    Host review\n        Hostname review.example.com\n        Port 29418\n        User tyrion\n\nSet ``git-config`` options\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nAdd an entry to your repository's Git config file for the Gerrit SSH\nhost above. Add an entry for your remote (note that this is necessary\nonly if the remote is named something other than \"origin\"). You can\nadd the entries by running the following commands, substituting the\ndetails according to your system: ::\n\n    git config git-change.remote <remote-name>\n    git config git-change.gerrit-ssh-host <gerrit-ssh-host>\n\nAs of version 0.2.0, `git-change` includes support for OWNERS files\n(see more information below). Add an entry if you want to turn on this\nfeature: ::\n\n    git config git-change.include_owners true\n\n\nInstall Git hooks\n~~~~~~~~~~~~~~~~~\n\n`Git-change` requires that you install the ``commit-msg`` hook that\nships with Gerrit. The hook ensures that every commit has a\n``Change-Id`` header in its commit message. Assuming you configured\nthe Gerrit SSH host above with the name ``review``, and that the\ncurrent working directory is the root of your local Git repository,\nrun the following command to install the hook: ::\n\n    scp -p review:hooks/commit-msg .git/hooks/\n\nIf you want `git-change` to inject bug IDs to your commit messages via\nthe ``--bug`` option, install the ``prepare-commit-msg`` hook script\nby copying the file from the ``extras`` directory of the `git-change`\nsource distribution to your repository's ``.git/hooks`` directory.\n\n\nWorkflow\n--------\n\nAfter hacking together a killer feature, stage the changed files and\nsend to Gerrit for review: ::\n\n    git add .\n    git change create --reviewers=arya\n\nThis commits the staged changes to a temporary, local *change*\n*branch*. The tracking branch you started from (``master``, for\nexample) is left in the state it was in before the changes, which\nmeans that you can now start on another change that does not depend on\nthe first change.\n\nNote that ``create`` is the default subcommand and can be omitted. So\n``git change --reviewers=arya`` does exactly the same thing as\nthe command above.\n\nThe change branch created by `git-change` includes the Change ID\ngenerated by the Gerrit ``commit-msg`` hook. It looks something like\n``change-I5372aa17af2c0ddc0de4c15688c605a0e668caa0``.\n\nAfter the reviewer has responded to your code review with feedback and\nyou've made the requested changes, switch to the change branch and use\n``git change update`` to push the changes as a new patch set: ::\n\n    git change list\n    git add .\n    git change update\n\n``git change list`` lists all your change branches and as a\nconvenience it provides a menu to select the one you want to switch\nto. You can also just switch using ``git checkout``. After you stage\nyour changes, running ``git change update`` adds the staged changes to\nthe current HEAD commit (by running ``git commit --amend`` behind the\nscenes) and pushes a new patch set to Gerrit.\n\nWhen it comes time to submit you can either use the Gerrit web\ninterface, or you can run ::\n\n    git change submit\n\nIf one or more of the files in your change was updated by someone else\nin the remote branch meanwhile, Gerrit will refuse to submit the\nchange. Usually in this case you need to pull the upstream changes\ninto your local tracking branch and from there rebase them into your\nchange branch, then finally push them back up to Gerrit as part of\nyour change. The ``rebase`` subcommand handles all of this for you in\none step: ::\n\n    git change rebase\n\nSometimes the rebase operation fails due to merge conflicts. If this\nhappens, resolve the conflicts and run ``git change rebase``\nagain. See git-rebase(1) for more information about how to proceed\nafter resolving conflicts.\n\nFinally, a word on housekeeping. Any change branches that accumulate\ncan be cleared out once the corresponding upstream commits have been\npulled into your local tracking branch by running ::\n\n    git change gc\n\nNote that only change branches that were created from the *current*\ntracking branch will be removed. If the current branch is ``master``\nbut you have old change branches created from the ``feature`` branch,\nyou have to switch to ``feature`` before running ``git change gc`` in\norder to clear out those branches. Of course, you can also remove\nstale change branches \"manually\" with ``git branch -d <branch>``.\n\n\n``OWNERS`` files\n----------------\n\n``OWNERS`` files are plaintext files in your codebase containing Gerrit\nusernames specifying the \"owners\" of directories and their\nsub-directories recursively.\n\nIf `git-change` support for ``OWNERS`` files is turned on (see the\nsection on Setup), every time a Gerrit changeset is created or\nupdated, `git-change` will attempt to read the relevant ``OWNERS``\nfiles and submit the change with the owners passed as Gerrit\nreviewers.\n\nFor example, let's say you are listed as an owner of a directory and\nsomeone else submits a change to Gerrit that includes a change to a\nfile in that directory: ::\n\n    git change create\n\n`Git-change` will read the ``OWNERS`` files relevant to the changeset\nand pass your username as a reviewer with the change. This means that\nfrom the perspective of Gerrit, the other programmer's command is\neffectively: ::\n\n    git change create --reviewers=your_username\n\n``OWNERS`` scope\n~~~~~~~~~~~~~~~~\n\n``OWNERS`` files have recursive scope. This means that if you are\nlisted as a owner of a directory, you are implicitly listed as an\nowner of that directory's sub-directories recursively. However,\n``OWNERS`` files are overridden by ``OWNERS`` files in\nsub-directories.\n\nFor example, in the case below, `a_file.py` and `a_file_test.py` are\nowned by the owners listed in ``OWNERS`` (A), but `configure_files.sh`\nis owned by the owners listed in ``OWNERS`` (B): ::\n\n    owners-example/\n    \u251c\u2500\u2500 a_file.py\n    \u251c\u2500\u2500 OWNERS       (A)\n    \u251c\u2500\u2500 scripts\n    \u2502   \u251c\u2500\u2500 configure_files.sh\n    \u2502   \u2514\u2500\u2500 OWNERS   (B)\n    \u2514\u2500\u2500 tests\n        \u2514\u2500\u2500 a_file_test.py\n\n\nCreating ``OWNERS`` files\n~~~~~~~~~~~~~~~~~~~~~~~~~\n\n``OWNERS`` files are plaintext files (named ``OWNERS`` in the\nfilesystem) that list Gerrit usernames, one per line. ``OWNERS`` files\ncan be added, edited and tracked with git like any other file: ::\n\n    $ cat owners-example/OWNERS\n    ayra\n    tyrion\n\n\nDocumentation\n-------------\n\nFor the full documentation see the ``git-change.rst`` file or the man\npage, ``git-change(1)``.\n\n\nExtras\n------\n\nThe ``extras`` directory of the source distribution contains the\nfollowing extras:\n\nBash completion\n~~~~~~~~~~~~~~~\n\nThis package includes a Bash completion script that completes command\nline option names and values. It depends on the completion script that\nships with Git. On Debian/Ubuntu systems, the ``git`` package installs\nthat script as ``/etc/bash_completion.d/git``.\n\nAdd the following lines to your Bash init file (e.g., ``~/.bashrc``),\nadjusting the paths as necessary for your system: ::\n\n    source /etc/bash_completion.d/git\n    source extras/bash_completion.d/git-change\n\nIf you use `virtualenv`_, you can source the `git-change` completion\nscript as follows: ::\n\n    source $VIRTUAL_ENV/etc/bash_completion.d/git-change\n\nYou can also define a list of reviewers in your organization so that\ntheir names appear as completion candidates for options like\n``--reviewers`` and ``--cc``. Place the list of reviewers according to\ntheir Gerrit user names in a text file, one per line. Then add this\nline to your Bash init file, adjusting the path as necessary: ::\n\n    export GIT_CHANGE_REVIEWERS_FILE=/path/to/file\n\nThis works for relatively small lists of reviewers, but probably does\nnot scale well for large organizations.\n\nHooks\n~~~~~\n\nThis package includes a ``prepare-commit-msg`` Git hook script which\ninjects a ``Bug`` header into commit messages if the ``BUG_ID``\nenvironment variable is set. ``git-commit create`` sets ``BUG_ID`` if\nyou pass it the ``--bug`` option.\n\n\nBugs\n----\n\nPlease report bugs on the GitHub `issues page`_.\n\n\nContributing\n------------\n\n`Git-change` is self-hosting; to contribute, first install\n`git-change`. Visit `Gerrit repository`_ to register for an account\nand upload your SSH key. See `Gerrit Uploading Changes`_ for more\ndetailed instructions.\n\nThen clone and configure the Gerrit repository, make your changes, and\nfinally use `git-change` to send a code review with your changes to\nthe `git-change` team: ::\n\n    git clone ssh://<sshusername>@review.opensource.nextdoor.com:29418/git-change.git\n    cd git-change\n    etc/configure-repository.sh\n    <make changes>\n    git add .\n    git change create\n\n\nSee also\n--------\n\nThe folks at OpenStack_ maintain a similar tool called `git-review`_.\n\n\n.. _Gerrit Code Review: http://code.google.com/p/gerrit/\n.. _Python Package Index: http://pypi.python.org/pypi/git-change\n.. _issues page: https://github.com/Nextdoor/git-change/issues\n.. _GitHub mirror: https://github.com/Nextdoor/git-change\n.. _virtualenv: http://www.virtualenv.org/\n.. _OpenStack: http://openstack.org/\n.. _git-review: https://github.com/openstack-ci/git-review\n.. _Nextdoor: http://www.nextdoor.com/\n.. _Gerrit repository: https://review.opensource.nextdoor.com/\n.. _Gerrit Uploading Changes:\n   https://review.opensource.nextdoor.com/Documentation/user-upload.html",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "http://pypi.python.org/pypi/git-change#downloads",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/Nextdoor/git-change",
        "keywords": "gerrit git code review",
        "license": "Apache License, Version 2.0",
        "maintainer": null,
        "maintainer_email": null,
        "name": "git-change",
        "package_url": "https://pypi.org/project/git-change/",
        "platform": "UNKNOWN",
        "project_url": "https://pypi.org/project/git-change/",
        "project_urls": {
            "Download": "http://pypi.python.org/pypi/git-change#downloads",
            "Homepage": "https://github.com/Nextdoor/git-change"
        },
        "release_url": "https://pypi.org/project/git-change/0.2.0/",
        "requires_dist": null,
        "requires_python": null,
        "summary": "Git command to create and manage Gerrit Code Review changes",
        "version": "0.2.0"
    },
    "last_serial": 1089859,
    "releases": {
        "0.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "5ba049c84fad4cc3ce05b82bab28ed7e",
                    "sha256": "9497015af2c50fee330c977fad3987db9b18b6461a3dc49d161a6f51264b9f11"
                },
                "downloads": -1,
                "filename": "git-change-0.1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "5ba049c84fad4cc3ce05b82bab28ed7e",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 19507,
                "upload_time": "2012-07-13T20:04:30",
                "url": "https://files.pythonhosted.org/packages/48/66/d3bced6a5b17c520983a8019646cf3ec4f3de659214dc288643fcf42aafc/git-change-0.1.0.tar.gz"
            }
        ],
        "0.1.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "86c7a5a4812ebde3d8c77ef6c9bf89e6",
                    "sha256": "5d9430d237c76ce9800e1ae92ed5b640d0771f13bf914f267296a36dc3278f87"
                },
                "downloads": -1,
                "filename": "git-change-0.1.1.tar.gz",
                "has_sig": false,
                "md5_digest": "86c7a5a4812ebde3d8c77ef6c9bf89e6",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 19642,
                "upload_time": "2013-02-02T00:41:41",
                "url": "https://files.pythonhosted.org/packages/b4/ef/ddac3af8b81d252449af8d549f19209ef975fb862c1b5bab91c4337ca7e0/git-change-0.1.1.tar.gz"
            }
        ],
        "0.2.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "aead6cdb80d0760b99e9fba910cd66af",
                    "sha256": "c64e9f064f2f28ed7907463382671be05a12b87eee7f195eb1e3c7e402d61c79"
                },
                "downloads": -1,
                "filename": "git-change-0.2.0.tar.gz",
                "has_sig": false,
                "md5_digest": "aead6cdb80d0760b99e9fba910cd66af",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 24242,
                "upload_time": "2014-05-12T19:10:39",
                "url": "https://files.pythonhosted.org/packages/00/64/5faad5b8cb7147fac4c2dd9e587cadac54f701cef90b7d98e0fff1613736/git-change-0.2.0.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "aead6cdb80d0760b99e9fba910cd66af",
                "sha256": "c64e9f064f2f28ed7907463382671be05a12b87eee7f195eb1e3c7e402d61c79"
            },
            "downloads": -1,
            "filename": "git-change-0.2.0.tar.gz",
            "has_sig": false,
            "md5_digest": "aead6cdb80d0760b99e9fba910cd66af",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 24242,
            "upload_time": "2014-05-12T19:10:39",
            "url": "https://files.pythonhosted.org/packages/00/64/5faad5b8cb7147fac4c2dd9e587cadac54f701cef90b7d98e0fff1613736/git-change-0.2.0.tar.gz"
        }
    ]
}