2

I'm using Sphinx to generate some documentation, and I publish this built documentation in a git repository. One of the files in the build directory is called environment.pickle and seems to be in binary format, i.e. not plaintext. What is this file, and should I include it when committing?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Newbyte
  • 2,421
  • 5
  • 22
  • 45
  • Why do you commit the built documentation? You should only need to keep the sources under version control. – mzjn Oct 28 '20 at 12:22
  • git is for source control, not build control. If you want to serve built documentation, do not host it in a repository, but use Read The Docs or some other hosting option. – Steve Piercy Oct 28 '20 at 12:29
  • 1
    @mzjn To host it on GitHub pages. – Newbyte Oct 29 '20 at 14:17

1 Answers1

2

Pickle files are a type of binary serialization format used by Python. They can be used for serializing Python objects into a binary form and then unserializing them later. You should never distribute pickle files because untrusted pickle files can execute arbitrary code during deserialization, according to the Python documentation:

It is possible to construct malicious pickle data which will execute arbitrary code during unpickling. Never unpickle data that could have come from an untrusted source, or that could have been tampered with.

In general, any object format which has the ability to serialize and deserialize arbitrary objects cannot be used on untrusted data, since the constructors and destructors of those objects could be leveraged to execute arbitrary code. Since nobody can securely use these pickle files, there's no reason to distribute them.

In general, you should not use Git for build artifacts, such as built documentation, either. Build artifacts are often binary and large, and these types of objects are unwieldy to work with in Git. Additionally, you probably are not interested in keeping the entire history of every build artifact, since you can just regenerate them from the source. A Git repository of such objects will quickly become bloated.

Using a different deployment format, such as tarballs, would be better. You haven't told us about where you're deploying these changes, so we can't provide you better advice on how to deploy this built documentation.

bk2204
  • 64,793
  • 6
  • 84
  • 100