{ "info": { "author": "Adam Spiers", "author_email": "git@adamspiers.org", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "Environment :: Console", "Intended Audience :: Developers", "License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)", "Natural Language :: English", "Operating System :: OS Independent", "Programming Language :: Python", "Topic :: Software Development :: Version Control", "Topic :: Utilities" ], "description": "===========\ngit-explode\n===========\n\n``git-explode`` is a tool for automatically exploding a single git\nbranch into a number of smaller branches which are textually\nindependent. It uses `git-deps\n`_ to automatically detect\ntextual dependencies between the commits in the branch, and calculates\nthe grouping and ordering of commits into independent sub-topics from\nwhich the new branches are created.\n\n\nUse case #1\n===========\n\nThe most obvious use case for this tool is helping improve the\n\"hygiene\" of branch management, so that each branch in your repository\nis tightly and cleanly scoped to a single logical topic.\n\nFor example during work on feature branch, you might become aware of\nan opportunity to refactor some existing code, and might decide to\ntake advantage of that opportunity immediately, by adding refactoring\ncommits to the tip of the feature branch. And during the refactoring,\nyou may even spot a bug, and end up also adding a bugfix to the same\nfeature branch.\n\nSo now you have a feature branch which is polluted by commits which\nperform refactoring and bugfixing. If you were to submit this branch\nfor code review as a single `GitHub pull request\n`_ (or `GitLab\nmerge request\n`_, or\n`Gerrit change topic\n`_),\nit would be a lot harder for your collaborators to review than if you\nhad separately submitted three smaller reviews, one for the bugfix,\none for the refactoring, and one for the new feature.\n\nIn this scenario, ``git-explode`` comes to the rescue! Rather than you\nhaving to manually separate out the commits into topic branches, it\ncan do all the hard work for you with a single command.\n\n\nTextual vs. semantic (in)dependence\n===================================\n\nAstute readers will note that textual independence (as detected by\n``git-deps`` and used by ``git-explode``) is not the same as semantic /\nlogical independence. Textual independence means that the changes can\nbe applied in any order without incurring conflicts, but this is not a\nreliable indicator of logical independence. (This caveat is also\nnoted in `the README for git-deps\n`_.)\n\nFor example a change to a function and corresponding changes to the\ntests and/or documentation for that function would typically exist in\ndifferent files. So if those changes were in separate commits within\na branch, running ``git-explode`` on the branch would place those\ncommits in separate branches even though they are logically related,\nbecause changes in different files (or even in different areas of the\nsame files) are textually independent.\n\nSo in this case, ``git-explode`` would not behave exactly how we might\nwant. And for as long as AI is an unsolved problem, it is very\nunlikely that it will ever develop totally reliable behaviour.\nSo does that mean ``git-explode`` is useless? Absolutely not!\n\nFirstly, when `best practices for commit hygiene\n`_ are adhered to,\nchanges which are strongly logically related should be within the same\ncommit anyway. So in the example above, a change to a function and\ncorresponding changes to the tests and/or documentation for that\nfunction should all be within a single commit.\n\nSecondly, whilst textual independence does not imply logical\nindependence, the converse is much more commonly true: logical\nindependence typically implies textual independence. So while it\nmight not be too uncommon for ``git-explode`` to separate\nlogically-related changes into different branches, it should be pretty\nrare that it groups logically *unrelated* changes on the same branch.\nCombining this with the fact that ``git`` makes it easier to merge\nbranches together than to split them apart suggests that ``git-explode``\nstill has plenty of potential for saving effort.\n\nThirdly, it is often unhelpful to allow `the quest for the perfect\nbecome the enemy of the good\n`_ - a\ntool does not have to be perfect to be useful; it only has to be\nbetter than performing the same task without the tool.\n\nFurther discussion on these points can be found in `an old thread from\nthe git mailing list\n`_.\n\nUltimately though, `\"the proof is in the pudding\"\n`_, so try\nit out and see!\n\n\nOther use cases\n===============\n\nAs already explained above, the most obvious use case is cleaning up\nthe mess caused by logically independent commits all mashed together\ninto one branch. However here are some further use cases. If you\ncan think of others, please `submit them `_!\n\n\nUse case #2: Decompose changes for porting\n------------------------------------------\n\nIf you need to backport or forward-port changes between two branches,\n``git-explode`` could be used to first decompose the source branch into\ntextually independent topic branches. Then before any porting starts,\ninformed decisions can be made about which topics to port and which\nnot to port, and in which order. Each decomposed topic branch is\nguaranteed to be textually independent from the others, so they can be\nported separately - indeed even concurrently by different people -\nthereby greatly reducing the risk of conflicts when the independent\ntopic branches are merged together into the target branch.\n\n\nUse case #3: Publishing a previously private codebase\n-----------------------------------------------------\n\nEmmet's idea about a company who needs to publish a private\ncodebase but needs to clean it up first. Similar to 1. but on a\nbigger scale.\n\n\nUse case #4: Breaking down giant commits\n----------------------------------------\n\nSplit giant commit into commits one per hunk, then regroup into\ncommits based on that.\n\n\nInstallation\n============\n\nPlease see `the INSTALL.rst file `_.\n\n\nUsage\n=====\n\nThe tool is not yet documented, but usage is fairly self-explanatory\nif you run ``git explode -h``.\n\n\nDevelopment / support / feedback\n================================\n\nPlease see `the CONTRIBUTING.rst file `_.\n\n\nHistory\n=======\n\nI first announced the intention to build this tool `on the git mailing\nlist in May 2016\n`_;\nhowever at the time I was under the mistaken impression that I could\nbuild it out of `the git-splice and git-transplant commands\n`_\nwhich I was working on at that time.\n\nThanks to SUSE's generous `Hack Week `_\npolicy, I have had the luxury of working on this as a `Hack Week project\n`_.\n\nIn May 2018 I took advantage of another Hack Week to apply more polish\nand make the first release. This was in preparation for demonstrating\nthe software at `a Meetup event\n`_ of the `Git\nLondon User Group `_.\n\n\nLicense\n=======\n\nReleased under `GPL version 2 `_ in order to be consistent\nwith `git's license\n`_, but I'm open to\nthe idea of dual-licensing if there's a convincing reason.", "description_content_type": "", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/aspiers/git-explode", "keywords": "", "license": "GPL-2+", "maintainer": "", "maintainer_email": "", "name": "git-explode", "package_url": "https://pypi.org/project/git-explode/", "platform": "", "project_url": "https://pypi.org/project/git-explode/", "project_urls": { "Homepage": "https://github.com/aspiers/git-explode" }, "release_url": "https://pypi.org/project/git-explode/0.0.1/", "requires_dist": null, "requires_python": "", "summary": "Explode linear sequence of commits into topic branches", "version": "0.0.1" }, "last_serial": 3881547, "releases": { "0.0.1": [ { "comment_text": "", "digests": { "md5": "9c2b15437694ddcfa8af1f318a058622", "sha256": "36ba06332766fe774c544a806e52bb491304e99cd7dbf1b7a85a8d6e991b01c1" }, "downloads": -1, "filename": "git-explode-0.0.1.tar.gz", "has_sig": false, "md5_digest": "9c2b15437694ddcfa8af1f318a058622", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 27040, "upload_time": "2018-05-20T21:06:40", "url": "https://files.pythonhosted.org/packages/2a/87/82341fde5e3cad957d0eea76fa826ffaf487158b78c2820ad105cf20f0f4/git-explode-0.0.1.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "9c2b15437694ddcfa8af1f318a058622", "sha256": "36ba06332766fe774c544a806e52bb491304e99cd7dbf1b7a85a8d6e991b01c1" }, "downloads": -1, "filename": "git-explode-0.0.1.tar.gz", "has_sig": false, "md5_digest": "9c2b15437694ddcfa8af1f318a058622", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 27040, "upload_time": "2018-05-20T21:06:40", "url": "https://files.pythonhosted.org/packages/2a/87/82341fde5e3cad957d0eea76fa826ffaf487158b78c2820ad105cf20f0f4/git-explode-0.0.1.tar.gz" } ] }