From 6e81840fc2a31a30250b8812dd3905fba9a2cdd1 Mon Sep 17 00:00:00 2001 From: Adam Spiers Date: Sun, 6 Jan 2019 13:04:43 +0000 Subject: update use cases --- README.md | 39 +++++++++++++++++++++++++++++++-------- 1 file changed, 31 insertions(+), 8 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index b027411..7ba8a8d 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,12 @@ Sometimes it is useful to understand the nature of parts of this DAG, as its nature will impact the success or failure of operations including merge, rebase, cherry-pick etc. +Several use cases are listed in detail below. They are also +[mentioned in the presentation I gave in September +2018](https://aspiers.github.io/denver-git-automagic-sept-2018/#/git-deps-motivation) +(see also [the video](https://youtu.be/f6anrSKCIgI?t=216)). + + ### Use case 1: porting between branches For example when porting a commit "A" between git branches via `git @@ -90,7 +96,7 @@ opportunities for selective pruning or other editing of commits during the backport process which may be able to reduce the number of commits which are required. -### Use case 2: splitting a patch series +### Use case 2: splitting a patch series into independent topics Large patch series or pull requests can be quite daunting for project maintainers, since they are hard to conquer in one sitting. For this @@ -108,6 +114,14 @@ will allow you to untangle things and expose subgraphs which can be cleanly split off into separate patch series or pull requests for submission. +In fact this technique is sufficiently useful but tedious to do +manually that I wrote a whole separate tool +[`git-explode`](https://github.com/aspiers/git-explode) to automate +the process. It uses `git-deps` as a library module behind the scenes +for the dependency inference. See [the +`README`](https://github.com/aspiers/git-explode/blob/master/README.rst) +for more details. + ### Use case 3: aiding collaborative communication Another use case might be to better understand levels of specialism / @@ -178,18 +192,27 @@ In the future, this script could be extended to optionally run the interactive `rebase`, so that the whole amendment process is taken care of by `git-fixup`. +### Use case 5: rewriting commit history + +It is often useful to reorder or rewrite commit history within private +branches, as part of a history polishing process which ensures that +eventually published history is of a high quality (see ["On Sausage +Making"](https://sethrobertson.github.io/GitBestPractices/#sausage)). + +However reordering or removing commits can cause conflicts. Whilst +`git-deps` can programmatically predict whether operations such as +merge / rebase / cherry-pick would succeed, actually it's probably +cheaper and more reliable simply to perform the operation and then +roll back. However `git-deps` could be used to detect ways to avoid +these conflicts, for example reordering or removing a commit's +dependencies along with the commit itself. In the future tools could +be built on top of `git-deps` to automate these processes. + ### Other uses I'm sure there are other use cases I haven't yet thought of. If you have any good ideas, [please submit them](CONTRIBUTING.md)! -### Non-use cases - -At first I thought that `git-deps` might provide a useful way to -programmatically predict whether operations such as merge / rebase / -cherry-pick would succeed, but actually it's probably cheaper and more -reliable simply to perform the operation and then roll back. - Installation ------------ -- cgit