[copyleft-next] [OT] tips/tricks/best practices for non-programmers using git for plain text documents?

Tom Marble tmarble at info9.net
Thu May 30 16:37:56 UTC 2013


On 05/29/2013 10:40 PM, Luis Villa wrote:
> For example, since non-programmers tend to pass around entire word docs instead of patches, they're likely to do all edits to a document and then submit a single gigantic change, instead of breaking it up into small functional changes (as is probably best practice). Compounding this (for me) is that I've often found it difficult to figure out how to cleanly break up patches into small bits in git. (I think there are some records of this in gitorious :)

Linksvayer had a very interesting approach here using
text based "markup" to handle the kinds of emphasis and
strikeout typically used in legal documents. He alludes
to this on list [0][1].

In this way it's possible to pass around these "wdiff"
files which are plain text.

I suspect that when working with a VCS such as git
that many, smaller changes are easier to handle
as each change can be accepted or rejected in its entirety.

I'm not sure of a best practice for selecting
*parts* of a proposed change (commit) without
resorting to selecting the differences by hand
in a text editor.

An example of wiff is:
$ w3m -dump 'http://www.datomic.com/datomic-free-edition-license.html' > datomic-free-edition-license-dump.txt
$ w3m -dump 'http://creativecommons.org/licenses/by-nd/3.0/legalcode' > cc-by-nd-30-dump.txt
$ wdiff -n cc-by-nd-30-dump.txt datomic-free-edition-license-dump.txt > datomic.wdiff

While that is readable I'm not aware of tools that can take wdiff
directly as a "patch".  Typically the patch tool requires a
"unified" diff:

$ diff -u cc-by-nd-30-dump.txt datomic-free-edition-license-dump.txt > datomic.diff
$ patch --verbose < datomic.diff
Hmm...  Looks like a unified diff to me...
The text leading up to this was:
--------------------------
|--- cc-by-nd-30-dump.txt	2013-05-30 10:36:59.627754808 -0500
|+++ datomic-free-edition-license-dump.txt	2013-05-30 10:36:53.443755066 -0500
--------------------------
Patching file cc-by-nd-30-dump.txt using Plan A...
Hunk #1 succeeded at 1.
done
$ sha256sum *.txt
11a6522300c2c35df28867a0dfdb1b7ed035576a392d8596c9a0bbbaa064a79c  cc-by-nd-30-dump.txt
11a6522300c2c35df28867a0dfdb1b7ed035576a392d8596c9a0bbbaa064a79c  datomic-free-edition-license-dump.txt
$

We can, however, use git to show wdiffs in color [2]:

$ git log Releases/copyleft-next-0.2.1
commit dbe07d8eb0a757b2e49281c878de50dfb4c9e84e
Author: Richard Fontana <fontana at sharpeleven.org>
Date:   Tue Mar 12 01:12:15 2013 -0400

    Add 0.2.1 to Releases.
$ git log Releases/copyleft-next-0.3.0
commit a4ed21d85fe7e2b75d4c70084f86eb138aeb8259
Author: Richard Fontana <fontana at sharpeleven.org>
Date:   Thu May 16 20:57:38 2013 -0400

    Add 0.3.0 to Releases.
$ git diff --word-diff --color dbe07d8eb0a757b2e49281c878de50dfb4c9e84e a4ed21d85fe7e2b75d4c70084f86eb138aeb8259 -- Drafts/copyleft-next
diff --git a/Drafts/copyleft-next b/Drafts/copyleft-next
index 9248ce3..f1d0fdc 100644
--- a/Drafts/copyleft-next
+++ b/Drafts/copyleft-next
@ -2,7 +2,7 @@ THIS IS A DRAFT. DO NOT USE AS A LICENSE.

                      copyleft-next ("this License")

1. License [-Grants-]{+Grants; No Trademark License+}

   Subject to the terms of this License, I grant You:

@@ -17,68 +17,60 @@ THIS IS A DRAFT. DO NOT USE AS A LICENSE.
   This License does not grant any rights in My name, trademarks, service
   marks, or logos.

2.[-Nullification of Copyleft/Proprietary Dual Licensing-]

....

So I think it would be nice if we had a patch tool that could take wdiffs
as we could use it to stage file changes (git commit).  Alternatively if
we could convert a wdiff to a unified diff then we could use the conventional
patch tool.  Alas one such tool, unify [3], isn't functional yet.

HTH,

--Tom

[0] https://lists.fedorahosted.org/pipermail/copyleft-next/2013-February/000440.html
[1] https://lists.fedorahosted.org/pipermail/copyleft-next/2013-February/000492.html
[2] https://idnotfound.wordpress.com/2009/05/09/word-by-word-diffs-in-git/
[3] https://www.gnu.org/software/wdiff/manual/html_node/unify-invocation.html#unify-invocation



More information about the copyleft-next mailing list