split off use cases to separate file

1 files changed, 154 insertions, 0 deletions

diff --git a/USE-CASES.md b/USE-CASES.md
new file mode 100644
index 0000000..40b87a5
--- /dev/null
+++ b/USE-CASES.md
@@ -0,0 +1,154 @@
+`git-deps` use cases
+======================
+
+Several use cases for `git-deps` 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](#use-case-1-porting-between-branches)
+- [Use case 2: splitting a patch series into independent topics](#use-case-2-splitting-a-patch-series-into-independent-topics)
+- [Use case 3: aiding collaborative communication](#use-case-3-aiding-collaborative-communication)
+- [Use case 4: automatic squashing of fixup commits](#use-case-4-automatic-squashing-of-fixup-commits)
+- [Use case 5: rewriting commit history](#use-case-5-rewriting-commit-history)
+
+### Use case 1: porting between branches
+
+For example when porting a commit "A" between git branches via `git
+cherry-pick`, it can be useful to programmatically determine in advance
+the minimum number of other dependent commits which would also need to
+be cherry-picked to provide the context for commit "A" to cleanly
+apply.  Here's a quick demo!
+
+[![YouTube porting screencast](./images/youtube-porting-thumbnail.png)](http://youtu.be/DVksJMXxVIM)
+
+**CAVEAT**: `git-deps` is not AI and only does a textual dependency
+analysis, therefore it does not guarantee there is no simpler way to
+backport.  It also may infer more dependencies than strictly necessary
+due the default setting of one line of fuzz (diff context).  Shrinking
+this to zero lines may produce a more conservative dependency tree,
+but it's also riskier and more likely to cause conflicts or even bad
+code on cherry-pick.  git-deps just provides a first estimate.
+
+Therefore combining it with human analysis of the commits in the
+dependency tree is strongly recommended.  This may reveal
+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 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
+reason it's generally best to keep the number of commits in any
+submission reasonably small.  However during normal hacking, you might
+accumulate a large number of patches before you start to contemplate
+submitting any of them upstream.  In this case, `git-deps` can help
+you determine how to break them up into smaller chunks.  Simply run
+
+    git deps -e $upstream_branch -s
+
+and then create a graph starting from the head of your local
+development branch, recursively expanding all the dependencies.  This
+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 /
+cross-functionality within an agile team.  If I author a commit which
+modifies (say) lines 34-37 and 102-109 of a file, the authors of the
+dependent commits are people I should potentially consider asking to
+review my commit, since I'm effectively changing "their" code.
+Monitoring those relationships over time might shed some light on how
+agile teams should best coordinate efforts on shared code bases.
+
+### Use case 4: automatic squashing of fixup commits
+
+It is often desirable to amend an existing commit which is in the
+current branch but not at its head.  This can be done by creating a
+new commit which amends (only) the existing commit, and then use `git
+rebase --interactive` in order to squash the two commits together into
+a new one which reuses the commit message from the original.
+`git-commit[1]` has a nice feature which makes this process convenient
+even when the commit to be amended is not at the head of the current
+branch.  It is described in [the `git-commit[1]` man
+page](https://git-scm.com/docs/git-commit):
+
+> `--fixup=<commit>`
+>
+> Construct a commit message for use with `rebase --autosquash`.  The
+> commit message will be the subject line from the specified commit
+> with a prefix of `"fixup! "`. See `git-rebase[1]` for details.
+
+The corresponding details in the [`git-rebase[1]` man
+page](https://git-scm.com/docs/git-rebase) are:
+
+> `--autosquash, --no-autosquash`
+>
+> When the commit log message begins with `"squash! ..."` (or `"fixup!
+> ..."`), and there is already a commit in the todo list that matches
+> the same ..., automatically modify the todo list of `rebase -i` so
+> that the commit marked for squashing comes right after the commit to
+> be modified, and change the action of the moved commit from pick to
+> squash (or fixup). A commit matches the ...  if the commit subject
+> matches, or if the ...  refers to the commit’s hash. As a fall-back,
+> partial matches of the commit subject work, too. The recommended way
+> to create fixup/squash commits is by using the `--fixup`/`--squash`
+> options of `git-commit(1)`
+
+However, this process still requires manually determining which commit
+should be passed to the `--fixup` option.  Fortunately `git-deps` can
+automate this for us.  To eliminate this extra work, this repository
+provides a simple script which wraps around `git-deps` to automate the
+whole process.  First the user should ensure that any desired
+amendments to the existing commit are staged in git's index.  Then
+they can run the `git-fixup` script which performs the following
+steps:
+
+1. These staged amendments to existing commit are committed using
+   temporary commit message.
+
+2. `git deps HEAD^!` is run to determine which previously existing
+   commit this new commit is intended to "patch".  This should only
+   result in a single dependency, otherwise the script aborts with an
+   error.
+
+3. The temporary commit's message is amended into the correct `fixup`
+   form.  On the next `git rebase --interactive` which includes the
+   original commit to be amended, `git-rebase` will automatically set
+   up the sequencer to apply the amendment (fixup) into the original.
+
+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)!