Merge branch 'master' into joeyconfig

39 files changed, 582 insertions, 24 deletions

diff --git a/doc/Linux.mdwn b/doc/Linux.mdwn
index 00276f69..ca0cfd65 100644
--- a/doc/Linux.mdwn
+++ b/doc/Linux.mdwn
@@ -1,5 +1,6 @@
 Propellor was written to manage Linux systems.
-It supports Debian and Debian-derived distributions.
+It supports Debian and Debian-derived distributions,
+as well as Arch Linux.
 
 Support for other distributions should not be too hard to add.
 Indeed, Propellor has been ported to [[FreeBSD]] now!
diff --git a/doc/forum/Docker.hs_will_Break_in_Stretch.mdwn b/doc/forum/Docker.hs_will_Break_in_Stretch.mdwn
new file mode 100644
index 00000000..c89c995c
--- /dev/null
+++ b/doc/forum/Docker.hs_will_Break_in_Stretch.mdwn
@@ -0,0 +1,16 @@
+G'day Joey!
+
+I'm in the process of deploying Docker infrastructure via Propellor on both Jessie and Stretch and I've come to discover that Docker.io did not make it into Stretch:
+
+* [docker.io REMOVED from testing](https://packages.qa.debian.org/d/docker.io/news/20161012T163916Z.html)
+* [docker.io - Linux container runtime](https://tracker.debian.org/pkg/docker.io)
+* [Excuse for docker.io](https://qa.debian.org/excuses.php?package=docker.io)
+
+So the below from Docker.hs will fail beyond Jessie:
+
+    installed :: Property DebianLike
+    installed = Apt.installed ["docker.io"]
+
+Before I embarked on my own path to re-implement the above (probably based on [How to install Docker engine on Debian 9 Stretch Linux](https://linuxconfig.org/how-to-install-docker-engine-on-debian-9-stretch-linux)), I thought I'd see what you thought might be the way to resolve this, so that my work could be contributed upstream (if suitable).
+
+Thanks!
diff --git a/doc/forum/Docker.hs_will_Break_in_Stretch/comment_1_8a4f16ae6d04b9d4bedb437ef333562b._comment b/doc/forum/Docker.hs_will_Break_in_Stretch/comment_1_8a4f16ae6d04b9d4bedb437ef333562b._comment
new file mode 100644
index 00000000..949f8d0c
--- /dev/null
+++ b/doc/forum/Docker.hs_will_Break_in_Stretch/comment_1_8a4f16ae6d04b9d4bedb437ef333562b._comment
@@ -0,0 +1,11 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 1"""
+ date="2017-02-02T17:28:49Z"
+ content="""
+Apparently the Debian way to install docker will be from backports.
+<https://bugs.debian.org/cgi-bin/bugreport.cgi?att=3;bug=781554;msg=9>
+
+Note that I'm no longer using any docker Properties myself, so
+propellor users who are will need to send patches..
+"""]]
diff --git a/doc/forum/Inherited_Variables....mdwn b/doc/forum/Inherited_Variables....mdwn
new file mode 100644
index 00000000..1535ec77
--- /dev/null
+++ b/doc/forum/Inherited_Variables....mdwn
@@ -0,0 +1,26 @@
+I've got a server defined in config.hs as follows:
+
+    myserver :: Host
+    myserver = host "myserver.mydomain" $ props
+        & standardSystem (Stable "jessie") X86_64 [ "Welcome to myserver!" ]
+
+I'm writing a module (to deploy Matrix, FWIW) which has a section like this:
+
+    sources :: Property Debian
+    sources = File.hasContent "/etc/apt/sources.list.d/matrix.list"
+                [ "# Deployed by Propellor"
+                , ""
+                , "deb http://matrix.org/packages/debian/ jessie main"
+                ] `onChange` Apt.update
+
+What I would like to be able to do, for example, is pull "jessie" from the standardSystem line into the sources function.
+
+The host name is another I'd like to be able to pull in, so that I can abstract as much as possible and wind up with a line that looks not unlike this:
+
+    & Matrix.server 
+
+Instead of
+
+    & Matrix.server hostname jessie
+
+Am I barking up the wrong tree and should I just embrace the latter?
diff --git a/doc/forum/Inherited_Variables.../comment_1_082e5d5b8e25335bc90577abcfef1d21._comment b/doc/forum/Inherited_Variables.../comment_1_082e5d5b8e25335bc90577abcfef1d21._comment
new file mode 100644
index 00000000..e4b32398
--- /dev/null
+++ b/doc/forum/Inherited_Variables.../comment_1_082e5d5b8e25335bc90577abcfef1d21._comment
@@ -0,0 +1,15 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 1"""
+ date="2017-01-26T06:39:35Z"
+ content="""
+This is where propellor's `Info` system comes in. `Propellor.Info.getOS`
+can be run to get the OS info.
+
+It's also possible to add new properties that add new values with custom
+types to `Info`.
+
+The hostname is not currently stored in `Info`, but it probably should be;
+that would be a good simplification. Currently there's a 
+separate way to get the hostname: `asks hostName` (run in the Propellor monad)
+"""]]
diff --git a/doc/forum/Inherited_Variables.../comment_2_988319ed6de46eff2eac0d5ef36382f9._comment b/doc/forum/Inherited_Variables.../comment_2_988319ed6de46eff2eac0d5ef36382f9._comment
new file mode 100644
index 00000000..676f41ac
--- /dev/null
+++ b/doc/forum/Inherited_Variables.../comment_2_988319ed6de46eff2eac0d5ef36382f9._comment
@@ -0,0 +1,15 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 2"""
+ date="2017-01-26T06:50:39Z"
+ content="""
+A worked example:
+
+	server :: Property Debian
+	server = property' "some description" $ \w -> do
+		os <- getOS
+		hostname <- asks hostName
+		ensureProperty w $
+			File.hasContent "/etc/apt/sources.list.d/matrix.list"
+				(genSourcesList os hostname)
+"""]]
diff --git a/doc/forum/Inherited_Variables.../comment_3_acf78fa9f732f070bf73c2ab601464ee._comment b/doc/forum/Inherited_Variables.../comment_3_acf78fa9f732f070bf73c2ab601464ee._comment
new file mode 100644
index 00000000..fcdf923b
--- /dev/null
+++ b/doc/forum/Inherited_Variables.../comment_3_acf78fa9f732f070bf73c2ab601464ee._comment
@@ -0,0 +1,8 @@
+[[!comment format=mdwn
+ username="craige"
+ avatar="http://cdn.libravatar.org/avatar/64ac5816ea3a51347d1f699022d1fdc1"
+ subject="Thanks!"
+ date="2017-01-27T21:54:45Z"
+ content="""
+Thanks Joey. I think that's exactly what I need. Very helpful :-)
+"""]]
diff --git a/doc/forum/Inherited_Variables.../comment_4_5bf7b1f69b48b4d9c516d424e4438208._comment b/doc/forum/Inherited_Variables.../comment_4_5bf7b1f69b48b4d9c516d424e4438208._comment
new file mode 100644
index 00000000..3b691b2a
--- /dev/null
+++ b/doc/forum/Inherited_Variables.../comment_4_5bf7b1f69b48b4d9c516d424e4438208._comment
@@ -0,0 +1,21 @@
+[[!comment format=mdwn
+ username="craige@a46118dff5bc0fad85259759970d8b4b9fc377d7"
+ nickname="craige"
+ avatar="http://cdn.libravatar.org/avatar/6d2207226de755da46aa2fdff9af70b2"
+ subject="comment 4"
+ date="2017-02-03T00:04:05Z"
+ content="""
+Ugh, sorry to ask again but I'm specifically stuck trying to extract the Debian suite only from this. Is this stored as a specific value I can draw on? I've been wading through the source and added in a swag of trial and error with no luck.
+
+I can see the suite listed in the output 
+
+    Just (System (Debian Linux (Stable \"jessie\"))
+
+but I was wondering if there was a method to pull out just the suite code name (ie: \"jessie\") that did not involve a regex looking for it amongst that output. 
+
+The goal is to query Info so that a suite name can be added to a sources list.
+
+If I have to regex, that's OK, I just didn't want to go down that path if there was a smarted way.
+
+Thanks Joey :-)
+"""]]
diff --git a/doc/forum/Inherited_Variables.../comment_5_6fbd29f568ec8b97be47874e2aac57a3._comment b/doc/forum/Inherited_Variables.../comment_5_6fbd29f568ec8b97be47874e2aac57a3._comment
new file mode 100644
index 00000000..16819bd6
--- /dev/null
+++ b/doc/forum/Inherited_Variables.../comment_5_6fbd29f568ec8b97be47874e2aac57a3._comment
@@ -0,0 +1,20 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 5"""
+ date="2017-02-03T19:32:58Z"
+ content="""
+What you're looking for is not a regexp, but Haskell's [pattern
+matching](https://www.haskell.org/tutorial/patterns.html).
+
+For example:
+
+	myproperty :: Property Debian
+	myproperty = withOS "some desc here" $ \w o -> case o of
+		-- Pattern match on the OS, to get the Debian stable release
+		(Just (System (Debian _kernel (Stable release)) _arch)) ->
+			ensureProperty w $ Apt.setSourcesListD (sourcesLines release) "mysources"
+		_ -> unsupportedOS
+
+	sourcesLines :: Release -> [Line]
+	sourcesLines release = undefined
+"""]]
diff --git a/doc/forum/Modules_with_Multiple_cmdProperty_causing_build_failures/comment_2_5afe0f200d7139499ef4b01ea6445206._comment b/doc/forum/Modules_with_Multiple_cmdProperty_causing_build_failures/comment_2_5afe0f200d7139499ef4b01ea6445206._comment
new file mode 100644
index 00000000..00f77116
--- /dev/null
+++ b/doc/forum/Modules_with_Multiple_cmdProperty_causing_build_failures/comment_2_5afe0f200d7139499ef4b01ea6445206._comment
@@ -0,0 +1,11 @@
+[[!comment format=mdwn
+ username="craige@a46118dff5bc0fad85259759970d8b4b9fc377d7"
+ nickname="craige"
+ avatar="http://cdn.libravatar.org/avatar/6d2207226de755da46aa2fdff9af70b2"
+ subject="Fixed!"
+ date="2017-01-26T05:54:22Z"
+ content="""
+The original suggestions did fix my problems. 
+
+Apologies for the late response.
+"""]]
diff --git a/doc/forum/Supported_OS/comment_3_f2924708a819b962ba7ed690019601ed._comment b/doc/forum/Supported_OS/comment_3_f2924708a819b962ba7ed690019601ed._comment
new file mode 100644
index 00000000..c03f6cd9
--- /dev/null
+++ b/doc/forum/Supported_OS/comment_3_f2924708a819b962ba7ed690019601ed._comment
@@ -0,0 +1,7 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""Arch too!"""
+ date="2017-02-04T21:30:26Z"
+ content="""
+Propellor just got support for Arch Linux!
+"""]]
diff --git a/doc/forum/propellor_and_gpg2/comment_1_4b732110f59f78f73fdfb745bdd9c0dd._comment b/doc/forum/propellor_and_gpg2/comment_1_4b732110f59f78f73fdfb745bdd9c0dd._comment
new file mode 100644
index 00000000..66c4cffa
--- /dev/null
+++ b/doc/forum/propellor_and_gpg2/comment_1_4b732110f59f78f73fdfb745bdd9c0dd._comment
@@ -0,0 +1,13 @@
+[[!comment format=mdwn
+ username="anselmi@0a9758305bef5e058dd0263fa20a27b334b482c7"
+ nickname="anselmi"
+ avatar="http://cdn.libravatar.org/avatar/65b723eb35eb4e3b05fffafd3e13e0fd"
+ subject="Cache gpg passphrase."
+ date="2016-12-22T17:23:58Z"
+ content="""
+The bottom line on this is that gpg2 (via the agent and pinentry) doesn't prompt correctly when run from git. It does when run directly.
+
+One fix is to set GPG_TTY before running propellor: `export GPG_TTY=$(tty)` or some such.
+
+Anything else that caches the pass phrase in the agent works too since that removes the need to prompt.
+"""]]
diff --git a/doc/install.mdwn b/doc/install.mdwn
index ad87cedc..f64519a7 100644
--- a/doc/install.mdwn
+++ b/doc/install.mdwn
@@ -1,4 +1,4 @@
-`git clone git://propellor.branchable.com/ propellor`  
+`git clone git://propellor.branchable.com/propellor`  
 Or get it [from github](https://github.com/joeyh/propellor).
 
 Propellor is recently available in Debian.
diff --git a/doc/news/Linux.Conf.Au.presentation.mdwn b/doc/news/Linux.Conf.Au.presentation.mdwn
new file mode 100644
index 00000000..54180979
--- /dev/null
+++ b/doc/news/Linux.Conf.Au.presentation.mdwn
@@ -0,0 +1,5 @@
+<video controls src="http://mirror.linux.org.au/pub/linux.conf.au/2017/Type_driven_configuration_management_with_Propellor.webm"></video>
+
+[video](http://mirror.linux.org.au/pub/linux.conf.au/2017/Type_driven_configuration_management_with_Propellor.webm)
+
+Also see this writeup in [Linux Weekly News](https://lwn.net/Articles/713653/)
diff --git a/doc/news/version_3.1.2.mdwn b/doc/news/version_3.1.2.mdwn
deleted file mode 100644
index b54b396a..00000000
--- a/doc/news/version_3.1.2.mdwn
+++ /dev/null
@@ -1,22 +0,0 @@
-propellor 3.1.2 released with [[!toggle text="these changes"]]
-[[!toggleable text="""
- * [ Joey Hess ]
-   * Ssh.knownHost: Bug fix: Only fix up the owner of the known\_hosts
-     file after it exists.
- * [ Sean Whitton ]
-   * Sbuild.keypairInsecurelyGenerated: Improved to be more robust.
-   * Pass --allow-unrelated-histories to git merge when run with git 2.9 or
-     newer. This fixes the /usr/bin/propellor wrapper with this version of git.
-   * Sbuild.built &amp; Sbuild.builtFor no longer require Sbuild.keypairGenerated.
-     Transition guide: If you are using sbuild 0.70.0 or newer, you should
-     `rm -r /var/lib/sbuild/apt-keys`.  Otherwise, you should add either
-     Sbuild.keypairGenerated or Sbuild.keypairInsecurelyGenerated to your host.
-   * Sbuild haddock improvements:
-     - State that we don't support squeeze and Buntish older than trusty.
-       This is due to our enhancements, such as eatmydata.
-     - State that you need sbuild 0.70.0 or newer to build for stretch.
-       This is due to gpg2 hitting Debian stretch.
-     - Explain when a keygen is required.
-     - Update sample ~/.sbuildrc for sbuild 0.71.0.
-     - Add hint for customising chroots with propellor.
-     - Update example usage of System type."""]]
\ No newline at end of file
diff --git a/doc/news/version_3.3.0.mdwn b/doc/news/version_3.3.0.mdwn
new file mode 100644
index 00000000..19bd5664
--- /dev/null
+++ b/doc/news/version_3.3.0.mdwn
@@ -0,0 +1,26 @@
+propellor 3.3.0 released with [[!toggle text="these changes"]]
+[[!toggleable text="""
+   * Arch Linux is now supported by Propellor!
+     Thanks to Zihao Wang for this port.
+   * Added Propellor.Property.Pacman for Arch's package manager.
+     Maintained by Zihao Wang.
+   * The types of some properties changed; eg from Property DebianLike
+     to Property (DebianLike + ArchLinux). Also, DebianLike and Linux
+     are no longer type synonyms; propellor now knows that Linux includes
+     ArchLinux. This could require updates to code, so is a minor API change.
+   * GHC's fileSystemEncoding is used for all String IO, to avoid
+     encoding-related crashes in eg, Propellor.Property.File.
+   * Add --build option to simply build config.hs.
+   * More informative usage message. Thanks, Daniel Brooks
+   * Tor.hiddenService' added to support multiple ports.
+     Thanks, Félix Sipma.
+   * Apt.noPDiffs added.
+     Thanks, Sean Whitton.
+   * stack.yaml: Compile with GHC 8.0.1 against lts-7.16.
+     Thanks, Andrew Cowie.
+   * Added Propellor.Property.File.configFileName and related functions
+     to generate good filenames for config directories.
+   * Added Apt.suiteAvailablePinned, Apt.pinnedTo.
+     Thanks, Sean Whitton.
+   * Added File.containsBlock
+     Thanks, Sean Whitton."""]]
\ No newline at end of file
diff --git a/doc/todo/Arch_Linux_Port.mdwn b/doc/todo/Arch_Linux_Port.mdwn
new file mode 100644
index 00000000..ac3ee4dc
--- /dev/null
+++ b/doc/todo/Arch_Linux_Port.mdwn
@@ -0,0 +1,16 @@
+Hi all, I'm an Arch Linux user and I've been learning Haskell and working on an Arch Liux Port in the last several months. Here's my [GitHub fork](https://github.com/wzhd/propellor/tree/archlinux), and the branch is called archlinux.
+
+Currently, I've added types, modified Bootstrap.hs, and added a Property for the package manager Pacman. I've been using it for a while and it seems to be working.
+
+I've made some addtional minor changes to make propellor compile without errors:
+
+- User.nuked now has type Property Linux
+- OS.cleanInstallOnce now has type Property DebianLike, because one of its dependencies, User.shadowConfig only supports DebianLike
+- tightenTargets is added to Reboot.toDistroKernel to get the expeted type
+- pattern for Arch Linux is added to Debootstrap.extractSuite to silence warning "non-exhaustive pattern match"
+- several properties in Parted and Partition are converted to Property Linux
+- Rsync.installed and Docker.installed now supports Pacman as well
+
+Hope you enjoy it!
+
+> [[merged|done]]; it was indeed enjoyable. thank you! --[[Joey]]
diff --git a/doc/todo/Arch_Linux_Port/comment_1_8e39dc177e21e9e20c1b74b59b9926d2._comment b/doc/todo/Arch_Linux_Port/comment_1_8e39dc177e21e9e20c1b74b59b9926d2._comment
new file mode 100644
index 00000000..11869a2a
--- /dev/null
+++ b/doc/todo/Arch_Linux_Port/comment_1_8e39dc177e21e9e20c1b74b59b9926d2._comment
@@ -0,0 +1,28 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 1"""
+ date="2017-02-03T19:14:41Z"
+ content="""
+Wow, nice work!
+
+Seems that Propellor.Property.Partition.formatted' is still a DebianLike
+property really, since it only supports using apt to install the mkfs
+programs. It will fail at runtime on Arch. So, I think best to keep it
+DebianLike until that's dealt with -- and then the type will be 
+`DebianLike + ArchLinux` rather than `LinuxLike`
+
+Same for Propellor.Property.Partition.kpartx.
+
+Several properties that were changed from DebianLike to Linux really
+only support DebianLike and ArchLinux, not all linux distros, so their
+types ought to be `DebianLike + ArchLinux`. This includes Docker.installed,
+Parted.installed, Rsync.installed.
+
+A nicer way to inplement those multi-distro `installed` properties is like
+this:
+
+	installed :: Property (Debian + ArchLinux)
+	installed = Apt.installed ["foo"] `pickOS` Pacman.installed ["foo"]
+
+Make those changes and I will merge it.
+"""]]
diff --git a/doc/todo/Arch_Linux_Port/comment_2_cc4623c156a0d12c88461bc5deec07cd._comment b/doc/todo/Arch_Linux_Port/comment_2_cc4623c156a0d12c88461bc5deec07cd._comment
new file mode 100644
index 00000000..dc6e3eb1
--- /dev/null
+++ b/doc/todo/Arch_Linux_Port/comment_2_cc4623c156a0d12c88461bc5deec07cd._comment
@@ -0,0 +1,18 @@
+[[!comment format=mdwn
+ username="wzhd"
+ avatar="http://cdn.libravatar.org/avatar/d5a499b7c476ca9960cc8dccdf455bae"
+ subject="comment 2"
+ date="2017-02-04T01:53:49Z"
+ content="""
+Thanks!
+
+
+I didn't find the right way to do it;  `pickOS` is so much easier than `withOS` !
+
+
+`Propellor.Property.Partition` was modified to get rid of some compiling errors in DiskImage and didn't support anything new. So I removed the changes.
+
+
+Instead,  I changed some properties in DiskImage from Linux to DebianLike.  Is it the correct way to do it?
+
+"""]]
diff --git a/doc/todo/Arch_Linux_Port/comment_3_d917de766dfe7fded7317d7614d1467f._comment b/doc/todo/Arch_Linux_Port/comment_3_d917de766dfe7fded7317d7614d1467f._comment
new file mode 100644
index 00000000..27ef8078
--- /dev/null
+++ b/doc/todo/Arch_Linux_Port/comment_3_d917de766dfe7fded7317d7614d1467f._comment
@@ -0,0 +1,25 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 3"""
+ date="2017-02-04T20:55:02Z"
+ content="""
+> Instead,  I changed some properties in DiskImage from Linux to
+> DebianLike.  Is it the correct way to do it?
+
+Looking at it, kpartx is DebianLike-specific, so imageBuiltFrom which uses it
+should be too. The only reason it wasn't marked as DebianLike already and
+was type Linux is because Linux used to be the same as DebianLike and so
+the type checker didn't see a difference. No longer, thanks to your patch.
+
+So, it makes complete sense that you have to change this. You're paying
+the price of blazing the trail of the first non-DebianLike Linux distro in
+Propellor..
+
+---
+
+Looks like your [[!commit 25f6871e1dda3de252fbc6c8ac6962eb0cd9311a]]
+dealt with all my review suggestions. And so, I've merged it.
+
+Unless you have anything else that needs to be done, I'll release
+propellor soon with the added Arch Linux support. Thank you very much!
+"""]]
diff --git a/doc/todo/Arch_Linux_Port/comment_4_924c73c0ab6fb39c9b25ae51facf6bb6._comment b/doc/todo/Arch_Linux_Port/comment_4_924c73c0ab6fb39c9b25ae51facf6bb6._comment
new file mode 100644
index 00000000..f69e2c80
--- /dev/null
+++ b/doc/todo/Arch_Linux_Port/comment_4_924c73c0ab6fb39c9b25ae51facf6bb6._comment
@@ -0,0 +1,8 @@
+[[!comment format=mdwn
+ username="wzhd"
+ avatar="http://cdn.libravatar.org/avatar/d5a499b7c476ca9960cc8dccdf455bae"
+ subject="comment 4"
+ date="2017-02-05T00:59:18Z"
+ content="""
+That's great! Thank you so much!
+"""]]
diff --git a/doc/todo/Are_--check_and_--build_on_the_way_in_or_on_the_way_out__63__.mdwn b/doc/todo/Are_--check_and_--build_on_the_way_in_or_on_the_way_out__63__.mdwn
new file mode 100644
index 00000000..52b3b998
--- /dev/null
+++ b/doc/todo/Are_--check_and_--build_on_the_way_in_or_on_the_way_out__63__.mdwn
@@ -0,0 +1,3 @@
+I've managed to do a few useful things with propellor, but it feels a bit rough around the edges to me. It looked at first like the --check and --build options would be useful for checking that my configs would at least compile, but it turns out that --build doesn't even exist and --check just returns without doing anything. Should they just be removed, or do they need more work to finish them?
+
+[[done]]
diff --git a/doc/todo/Are_--check_and_--build_on_the_way_in_or_on_the_way_out__63__/comment_1_7c2b2447254ad44ee1316b47eac130df._comment b/doc/todo/Are_--check_and_--build_on_the_way_in_or_on_the_way_out__63__/comment_1_7c2b2447254ad44ee1316b47eac130df._comment
new file mode 100644
index 00000000..392f0f1c
--- /dev/null
+++ b/doc/todo/Are_--check_and_--build_on_the_way_in_or_on_the_way_out__63__/comment_1_7c2b2447254ad44ee1316b47eac130df._comment
@@ -0,0 +1,12 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 1"""
+ date="2016-12-26T15:55:36Z"
+ content="""
+--check does just what it's supposed to do. This is used during bootstrap
+to notice if the propellor binary has gotten broken by changes to eg system
+libraries.
+
+--build seems to have been added without being implemented.  But it does
+seem  useful to have a way to simply build propellor so implemented it now.
+"""]]
diff --git a/doc/todo/Are_--check_and_--build_on_the_way_in_or_on_the_way_out__63__/comment_2_b4910f50225a8b763566126861faea11._comment b/doc/todo/Are_--check_and_--build_on_the_way_in_or_on_the_way_out__63__/comment_2_b4910f50225a8b763566126861faea11._comment
new file mode 100644
index 00000000..0c594483
--- /dev/null
+++ b/doc/todo/Are_--check_and_--build_on_the_way_in_or_on_the_way_out__63__/comment_2_b4910f50225a8b763566126861faea11._comment
@@ -0,0 +1,8 @@
+[[!comment format=mdwn
+ username="db48x"
+ avatar="http://cdn.libravatar.org/avatar/ad2688127feb555a92154b16d8eeb5d3"
+ subject="aha"
+ date="2016-12-26T21:23:03Z"
+ content="""
+Thanks!
+"""]]
diff --git a/doc/todo/Merging_from___47__usr__47__src__47__propellor_broken_now_CHANGELOG_not_a_symlink.mdwn b/doc/todo/Merging_from___47__usr__47__src__47__propellor_broken_now_CHANGELOG_not_a_symlink.mdwn
new file mode 100644
index 00000000..bfba8548
--- /dev/null
+++ b/doc/todo/Merging_from___47__usr__47__src__47__propellor_broken_now_CHANGELOG_not_a_symlink.mdwn
@@ -0,0 +1,36 @@
+In Joey's master branch, `CHANGELOG` is a real file, whereas previously it was a symlink.  This breaks the `/usr/src/propellor` newer version check.
+
+Steps to reproduce:
+
+1. Install propellor 3.2.3 or older with apt on Debian or Ubuntu
+2. `propellor --init` and select option `A`
+3. Prepare a pseudorelease: merge Joey's master branch into [my Debian packaging branch](https://git.spwhitton.name/?p=propellor.git;a=shortlog;h=refs/heads/debian), `dch -v3.2.3+gitYYYYMMDD.fffffff`, `dpkg-buildpackage -uc -b`, `debi -u`
+4. `propellor --spin`
+
+I haven't yet tried reproducing this by building a `.deb` from Joey's master branch, rather than my packaging branch.  If the problem does not appear using a `.deb` from Joey's master branch, this is an internal Debian problem, rather than an upstream bug.  However, perhaps Joey can immediately see a solution.
+
+Sample output:
+
+    Auto-merging src/wrapper.hs
+    Auto-merging src/Utility/UserInfo.hs
+    Auto-merging src/Utility/SystemDirectory.hs
+    Auto-merging src/Utility/Misc.hs
+    Auto-merging src/Utility/FileSystemEncoding.hs
+    Auto-merging src/Utility/Exception.hs
+    Auto-merging src/Propellor/Types/CmdLine.hs
+    Auto-merging src/Propellor/Shim.hs
+    Auto-merging src/Propellor/Property/Gpg.hs
+    Auto-merging src/Propellor/Property/Debootstrap.hs
+    Auto-merging src/Propellor/Property.hs
+    Auto-merging src/Propellor/PrivData.hs
+    Auto-merging src/Propellor/Gpg.hs
+    Auto-merging src/Propellor/CmdLine.hs
+    Auto-merging debian/changelog
+    Auto-merging CHANGELOG
+    CONFLICT (add/add): Merge conflict in CHANGELOG
+    Automatic merge failed; fix conflicts and then commit the result.
+    propellor: Failed to run git ["merge","c590ddd8e2fa87baa409b6c29501d4473555ecfb","-s","recursive","-Xtheirs","--quiet","-m","merging upstream version","--allow-unrelated-histories"]
+    CallStack (from HasCallStack):
+      error, called at src/Propellor/DotDir.hs:425:17 in main:Propellor.DotDir
+
+--spwhitton
diff --git a/doc/todo/Merging_from___47__usr__47__src__47__propellor_broken_now_CHANGELOG_not_a_symlink/comment_1_62b47d7c0530c2988b7e6e998878b920._comment b/doc/todo/Merging_from___47__usr__47__src__47__propellor_broken_now_CHANGELOG_not_a_symlink/comment_1_62b47d7c0530c2988b7e6e998878b920._comment
new file mode 100644
index 00000000..886c2534
--- /dev/null
+++ b/doc/todo/Merging_from___47__usr__47__src__47__propellor_broken_now_CHANGELOG_not_a_symlink/comment_1_62b47d7c0530c2988b7e6e998878b920._comment
@@ -0,0 +1,11 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 1"""
+ date="2017-01-01T21:29:52Z"
+ content="""
+I have reverted that change for now.
+
+I don't think the /usr/src/propellor/ merge has anything specific to do
+with the changelog, so there is probably a general case where that merge
+fails to work. I guess it involves a file's type changing.
+"""]]
diff --git a/doc/todo/Merging_from___47__usr__47__src__47__propellor_broken_now_CHANGELOG_not_a_symlink/comment_2_61463030200038542d293149754d36ed._comment b/doc/todo/Merging_from___47__usr__47__src__47__propellor_broken_now_CHANGELOG_not_a_symlink/comment_2_61463030200038542d293149754d36ed._comment
new file mode 100644
index 00000000..b1b4a037
--- /dev/null
+++ b/doc/todo/Merging_from___47__usr__47__src__47__propellor_broken_now_CHANGELOG_not_a_symlink/comment_2_61463030200038542d293149754d36ed._comment
@@ -0,0 +1,8 @@
+[[!comment format=mdwn
+ username="spwhitton"
+ avatar="http://cdn.libravatar.org/avatar/9c3f08f80e67733fd506c353239569eb"
+ subject="comment 2"
+ date="2017-01-03T09:07:18Z"
+ content="""
+Thanks for looking at this.  Yes, it's probably the type-change.  There is surely some way to instruct git to DTRT.
+"""]]
diff --git a/doc/todo/hostChroot.mdwn b/doc/todo/hostChroot.mdwn
new file mode 100644
index 00000000..eccfd641
--- /dev/null
+++ b/doc/todo/hostChroot.mdwn
@@ -0,0 +1,7 @@
+Would be useful to have a `hostChroot :: Host -> Chroot`.
+
+For a Debian host, this would use debootstrapped and pass all the Host's
+properties to it. --[[Joey]] 
+
+Would need to make privdata use the context of the input Host. And would
+need to propigate privdata info, but not other info. --[[Joey]]
diff --git a/doc/todo/modify_Apt.pinnedTo_to_pin_a_package_to_multiple_suites_with_different_priorities.mdwn b/doc/todo/modify_Apt.pinnedTo_to_pin_a_package_to_multiple_suites_with_different_priorities.mdwn
new file mode 100644
index 00000000..02be4ad7
--- /dev/null
+++ b/doc/todo/modify_Apt.pinnedTo_to_pin_a_package_to_multiple_suites_with_different_priorities.mdwn
@@ -0,0 +1,7 @@
+Please consider merging the `pin` branch of `https://git.spwhitton.name/propellor` (again).
+
+I've modified `Apt.pinnedTo` so that it can pin an `AptPrefPackage` to multiple suites with different pin priorities.  I've included a sample use-case in the function's haddock.
+
+--spwhitton
+
+> merged, [[done]] --[[Joey]]
diff --git a/doc/todo/new_apt_pinning_properties.mdwn b/doc/todo/new_apt_pinning_properties.mdwn
new file mode 100644
index 00000000..8687b58a
--- /dev/null
+++ b/doc/todo/new_apt_pinning_properties.mdwn
@@ -0,0 +1,10 @@
+My branch `pin` of repo `https://git.spwhitton.name/propellor` adds
+
+- `Apt.suiteAvailablePinned`
+- `Apt.pinnedTo`
+- `File.containsBlock`
+- a haddock for `File.containsLines`
+
+There is one TODO in a comment that relates to propellor's algebraic data types.  I'd be grateful for help with that.  --spwhitton
+
+> merged, thanks. [[done]] --[[Joey]]
diff --git a/doc/todo/new_apt_pinning_properties/comment_1_fd9e6775868eaa8d6aee49d06944ef0c._comment b/doc/todo/new_apt_pinning_properties/comment_1_fd9e6775868eaa8d6aee49d06944ef0c._comment
new file mode 100644
index 00000000..4800608f
--- /dev/null
+++ b/doc/todo/new_apt_pinning_properties/comment_1_fd9e6775868eaa8d6aee49d06944ef0c._comment
@@ -0,0 +1,38 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 1"""
+ date="2017-02-01T20:00:47Z"
+ content="""
+I wonder if it would be better to separate `suiteAvailablePinned`
+into `suiteAvailable` and `suitePinned`? The latter could require
+the former.
+
+`pinnedTo` should probably be DebianLike not UnixLike.
+And its `[String]` parameter ought to be `[Package]`.
+
+Is `File.containsBlock` necessary? Seems that if you care about
+ordering of blocks in the file, you generally should use
+`File.hasContent` to specify the full content. Rather than using
+/etc/apt/preferences.d/10propellor.pref for multiple properties,
+you could use a separate file for each `pinnedTo'` with the parameters
+encoded in the filename.
+
+As to the TODO, I tried adding this:
+
+	robustly' :: RevertableProperty DebianLike DebianLike -> RevertableProperty DebianLike DebianLike
+	robustly' p = p `fallback` (update `before` p)
+
+And the compiler tells me it's wrong because `update` is not revertable.
+But of course, there's no need to revert apt-get update, so this compiles:
+
+	robustly' :: RevertableProperty DebianLike DebianLike -> RevertableProperty DebianLike DebianLike
+	robustly' p = p `fallback` ((update <!> (doNothing :: Property DebianLike)) `before` p)
+
+Cleaning it up left an an exersise for the reader. Might be possible
+to combine `robustly` and `robustly'` into a single function, but I'm
+not able to see how immediately.
+
+However.. Seems to me that whatever you wanted to use `robustly` with to
+spur that TODO, you could just apply it to the first Property of the
+RevertableProperty, and not to the second one?
+"""]]
diff --git a/doc/todo/new_apt_pinning_properties/comment_2_c82f7e83f3fcc7648222d9dbf90e5ddd._comment b/doc/todo/new_apt_pinning_properties/comment_2_c82f7e83f3fcc7648222d9dbf90e5ddd._comment
new file mode 100644
index 00000000..4fd7c824
--- /dev/null
+++ b/doc/todo/new_apt_pinning_properties/comment_2_c82f7e83f3fcc7648222d9dbf90e5ddd._comment
@@ -0,0 +1,66 @@
+[[!comment format=mdwn
+ username="spwhitton"
+ avatar="http://cdn.libravatar.org/avatar/9c3f08f80e67733fd506c353239569eb"
+ subject="reply to review"
+ date="2017-02-02T17:40:11Z"
+ content="""
+Thank you for your feedback, Joey.
+
+> I wonder if it would be better to separate `suiteAvailablePinned`
+> into `suiteAvailable` and `suitePinned`? The latter could require
+> the former.
+
+I see how this could be useful, in particular if you want to make a
+suite like Debian experimental available, which won't cause any packages
+to be automatically upgraded.
+
+However, it makes it less convenient, and perhaps dangerous, to revert a
+pinned suite.  For example, suppose on my Debian testing system I have
+`Apt.suitePinned Unstable 100`.  If I revert this property, it will
+remove the pin but not remove the source.  Then my system might get
+mass-upgraded to sid if I'm not careful.
+
+We couldn't have the revert of `Apt.suitePinned` remove the source
+because then if I have both `& Apt.suiteAvailable Unstable` and `!
+Apt.suitePinned Unstable 100`, the second property would cancel out the
+first, which doesn't make sense.
+
+On balance, I think it's best to keep the current property.  A property
+adding sources to apt.sources.d should probably force the user to pick a
+pin value, to avoid any unexpected upgrades.
+
+> `pinnedTo` should probably be DebianLike not UnixLike.
+
+This was my 'TODO'.  (Since the property takes a `DebianSuite`, I think
+it should be `Debian` not `DebianLike`.)
+
+I tried applying `tightenTargets` to `pinnedTo`, but that only seems to
+affect one half of the revertable property.  Do I need to implement a
+new tightening function?
+
+> And its `[String]` parameter ought to be `[Package]`.
+
+I don't think so.  The parameter to `pinnedTo` can be a wildcard
+expression or a regex (per `apt_preferences(5)`).  Neither of these are
+accepted by other existing properties that take `[Package]`, such as
+`Apt.installed`.  I could add a new type alias, if you prefer.
+
+> Is `File.containsBlock` necessary? Seems that if you care about
+> ordering of blocks in the file, you generally should use
+> `File.hasContent` to specify the full content. Rather than using
+> /etc/apt/preferences.d/10propellor.pref for multiple properties,
+> you could use a separate file for each `pinnedTo'` with the parameters
+> encoded in the filename.
+
+This was what I tried on my first attempt, but it gets very complicated
+if the user passes a wildcard expression or a regex instead of a package
+name.  I would need to convert that wildcard expression or regex to a
+cross-platform filename, and the conversion would need to be isomorphic
+to avoid any clashes.  The `File.containsBlock` seems more sane than
+that.
+
+> As to the TODO, I tried adding this: [...]
+
+I don't understand how `robustly` is relevant to my TODO -- please see
+above.
+"""]]
diff --git a/doc/todo/new_apt_pinning_properties/comment_3_58d323602f293471ce3d2d9b4d271130._comment b/doc/todo/new_apt_pinning_properties/comment_3_58d323602f293471ce3d2d9b4d271130._comment
new file mode 100644
index 00000000..b0ff271e
--- /dev/null
+++ b/doc/todo/new_apt_pinning_properties/comment_3_58d323602f293471ce3d2d9b4d271130._comment
@@ -0,0 +1,23 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 3"""
+ date="2017-02-02T18:45:01Z"
+ content="""
+That example with reverting one property overriding another property
+is a general problem propellor has with conflicting properties. 
+Normally I don't much worry about it, but I agree an accidental mass
+upgrade is a good reason to avoid that problem here.
+
+Yes please add a new type alias for String (or an ADT) 
+if Package is not appropriate.
+
+I had misunderstood which function the TODO was for..
+
+Nice surprise that tightenTargets works on RevertableProperty at all.
+Since it does, you should be able to tighten one side, revert, tighten the
+other side, and re-revert. Or, deconstruct the RevertableProperty, 
+tighten both sides individually, and reconstruct it.
+
+I've added a Propellor.Property.File.configFileName that 
+should be suitable for your purposes, and others..
+"""]]
diff --git a/doc/todo/new_apt_pinning_properties/comment_4_add83ed58963e944ccd705a50e8b5a47._comment b/doc/todo/new_apt_pinning_properties/comment_4_add83ed58963e944ccd705a50e8b5a47._comment
new file mode 100644
index 00000000..9688672b
--- /dev/null
+++ b/doc/todo/new_apt_pinning_properties/comment_4_add83ed58963e944ccd705a50e8b5a47._comment
@@ -0,0 +1,20 @@
+[[!comment format=mdwn
+ username="spwhitton"
+ avatar="http://cdn.libravatar.org/avatar/9c3f08f80e67733fd506c353239569eb"
+ subject="comment 4"
+ date="2017-02-03T04:07:58Z"
+ content="""
+> Yes please add a new type alias for String (or an ADT) if Package is not appropriate.
+
+Propellor won't be parsing any of the regexp or globs, so I've added a new type alias rather than an ADT.
+
+> Nice surprise that tightenTargets works on RevertableProperty at all. Since it does, you should be able to tighten one side, revert, tighten the other side, and re-revert. Or, deconstruct the RevertableProperty, tighten both sides individually, and reconstruct it.
+
+I don't understand what you're getting at with the first of these suggestions.
+
+In any case, now that I'm not using `File.containsBlock`, it's easy to just apply `tightenTargets` to each side.
+
+> I've added a Propellor.Property.File.configFileName that should be suitable for your purposes, and others..
+
+Very nice :)  I've updated my branch to use this.  I haven't removed `File.containsBlock`, since it might be useful in the future, but you could of course revert the relevant commit.
+"""]]
diff --git a/doc/todo/usage__47__help_text_improvements.mdwn b/doc/todo/usage__47__help_text_improvements.mdwn
new file mode 100644
index 00000000..80fffb3d
--- /dev/null
+++ b/doc/todo/usage__47__help_text_improvements.mdwn
@@ -0,0 +1,3 @@
+I started out looking at how to make usage.mdwn into a man page, but that's a little more work than I wanted to do tonight. Instead, I added more information to the usage message. Commit is fa0e8d83 on iabak:~db48x/propellor if you want it.
+
+> merged [[done]] tnx --[[Joey]] 
diff --git a/doc/todo/usage__47__help_text_improvements/comment_1_66878945cdb57d06849337262d939701._comment b/doc/todo/usage__47__help_text_improvements/comment_1_66878945cdb57d06849337262d939701._comment
new file mode 100644
index 00000000..f30eae46
--- /dev/null
+++ b/doc/todo/usage__47__help_text_improvements/comment_1_66878945cdb57d06849337262d939701._comment
@@ -0,0 +1,13 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 1"""
+ date="2016-12-27T02:46:19Z"
+ content="""
+I don't like the use of tabs in that; it may be that with some terminal
+with an unusual tab stop, the things don't align.
+
+It would probably be simplest to put the description in the line under the
+option.
+
+BTW, the Makefile can build propellor.1 out of usage.mdwn
+"""]]
diff --git a/doc/todo/usage__47__help_text_improvements/comment_2_d531a45851cdef87a8f7b8182b3d04ce._comment b/doc/todo/usage__47__help_text_improvements/comment_2_d531a45851cdef87a8f7b8182b3d04ce._comment
new file mode 100644
index 00000000..62cf1fe4
--- /dev/null
+++ b/doc/todo/usage__47__help_text_improvements/comment_2_d531a45851cdef87a8f7b8182b3d04ce._comment
@@ -0,0 +1,12 @@
+[[!comment format=mdwn
+ username="db48x"
+ avatar="http://cdn.libravatar.org/avatar/ad2688127feb555a92154b16d8eeb5d3"
+ subject="comment 2"
+ date="2016-12-27T06:12:52Z"
+ content="""
+/me facepalms; of course it can. I guess I saw the 'git commit' in the install target and disregarded the rest.
+
+I removed the tabs from the usage. It's a lot longer, but I suppose it gets the job done.
+
+
+"""]]
diff --git a/doc/usage.mdwn b/doc/usage.mdwn
index fec346ae..3d32538f 100644
--- a/doc/usage.mdwn
+++ b/doc/usage.mdwn
@@ -55,6 +55,14 @@ and configured in haskell.
   The hostname given to --spin can be a short name, which is
   then looked up in the DNS to find the FQDN.
 
+* propellor --build
+
+  Causes propellor to build itself, checking that your config.hs, etc are
+  valid.
+
+  You do not need to run this as a separate step; propellor automatically
+  builds itself when using things like --spin.
+
 * propellor --add-key keyid
 
   Adds a gpg key, which is used to encrypt the privdata.
@@ -66,6 +74,10 @@ and configured in haskell.
   using this key. Propellor requires signed commits when pulling from
   a central git repository.
 
+* propellor --rm-key keyid
+
+  Stops encrypting the privdata to a gpg key.
+
 * propellor --list-fields
 
   Lists all privdata fields that are used by your propellor configuration.
diff --git a/doc/user/craige.mdwn b/doc/user/craige.mdwn
new file mode 100644
index 00000000..775e2fb0
--- /dev/null
+++ b/doc/user/craige.mdwn
@@ -0,0 +1 @@
+It's been said I was the fourth user :-)