Re-describe each commit.

[git-central.git] / server / functions

diff --git a/server/functions b/server/functions
index 28ad90f..ff16d51 100644 (file)
--- a/server/functions
+++ b/server/functions
@@ -8,6 +8,83 @@
 # as it will replace only the first match, compared to the canonical "grep -v"
 # approach which will throw out multiple matches if the same commit is referred
 # to by multiple branches.
+#
+# Excellent, excellent docs from Andy Parkin's email script
+#
+##################################################
+#
+# Consider this:
+#   1 --- 2 --- O --- X --- 3 --- 4 --- N
+#
+# O is $oldrev for $refname
+# N is $newrev for $refname
+# X is a revision pointed to by some other ref, for which we may
+#   assume that an email has already been generated.
+# In this case we want to issue an email containing only revisions
+# 3, 4, and N.  Given (almost) by
+#
+#  git rev-list N ^O --not --all
+#
+# The reason for the "almost", is that the "--not --all" will take
+# precedence over the "N", and effectively will translate to
+#
+#  git rev-list N ^O ^X ^N
+#
+# So, we need to build up the list more carefully.  git rev-parse
+# will generate a list of revs that may be fed into git rev-list.
+# We can get it to make the "--not --all" part and then filter out
+# the "^N" with:
+#
+#  git rev-parse --not --all | grep -v N
+#
+# Then, using the --stdin switch to git rev-list we have effectively
+# manufactured
+#
+#  git rev-list N ^O ^X
+#
+# This leaves a problem when someone else updates the repository
+# while this script is running.  Their new value of the ref we're
+# working on would be included in the "--not --all" output; and as
+# our $newrev would be an ancestor of that commit, it would exclude
+# all of our commits.  What we really want is to exclude the current
+# value of $refname from the --not list, rather than N itself.  So:
+#
+#  git rev-parse --not --all | grep -v $(git rev-parse $refname)
+#
+# Get's us to something pretty safe (apart from the small time
+# between refname being read, and git rev-parse running - for that,
+# I give up)
+#
+#
+# Next problem, consider this:
+#   * --- B --- * --- O ($oldrev)
+#          \
+#           * --- X --- * --- N ($newrev)
+#
+# That is to say, there is no guarantee that oldrev is a strict
+# subset of newrev (it would have required a --force, but that's
+# allowed).  So, we can't simply say rev-list $oldrev..$newrev.
+# Instead we find the common base of the two revs and list from
+# there.
+#
+# As above, we need to take into account the presence of X; if
+# another branch is already in the repository and points at some of
+# the revisions that we are about to output - we don't want them.
+# The solution is as before: git rev-parse output filtered.
+#
+# Finally, tags: 1 --- 2 --- O --- T --- 3 --- 4 --- N
+#
+# Tags pushed into the repository generate nice shortlog emails that
+# summarise the commits between them and the previous tag.  However,
+# those emails don't include the full commit messages that we output
+# for a branch update.  Therefore we still want to output revisions
+# that have been output on a tag email.
+#
+# Luckily, git rev-parse includes just the tool.  Instead of using
+# "--all" we use "--branches"; this has the added benefit that
+# "remotes/" will be ignored as well.
+#
+##################################################
 function set_new_commits() {
        nl=$'\n'
 
@@ -69,9 +146,14 @@ function set_rev_types() {
 #
 # The email subject will contain the best description of the ref that we can build from the parameters
 function set_describe() {
-       describe=$(git describe $rev 2>/dev/null)
+       rev_to_describe="$rev"
+       if [ "$1" != "" ] ; then
+               rev_to_describe="$1"
+       fi
+
+       describe=$(git describe $rev_to_describe 2>/dev/null)
        if [ -z "$describe" ]; then
-               describe=$rev
+               describe=$rev_to_describe
        fi
 }