blob/fileblob: Add docstring about tempdirs

blob/fileblob/fileblob.go

@@ -15,6 +15,16 @@
 // Package fileblob provides a blob implementation that uses the filesystem.
 // Use OpenBucket to construct a *blob.Bucket.
 //
+// To avoid partial writes, fileblob writes to a temporary file and then renames
+// the temporary file to the final path on Close. By default, it creates these
+// temporary files in `os.TempDir`. If `os.TempDir` is on a different mount than
+// your base bucket path, the `os.Rename` will fail with `invalid cross-device link`.
+// To avoid this, either:
+// a) Configure the temp dir to use by setting the environment variable `TMPDIR`.
+// b) Set `Options.NoTempDir` to `true`; fileblob will create the temporary files
+//    next to the actual files instead of in a temporary directory. Note that
+//    this may result in stranded temporary files.
+//
 // By default fileblob stores blob metadata in 'sidecar files' under the original
 // filename but an additional ".attrs" suffix.
 // That behaviour can be changed via Options.Metadata;