In order to visualize some concepts in a Git repo for other developers, I want to put there some vector drawings. Of course they should not be binary. If minor changes occur, the file change should be minor as well. Up to this point I think about the flat XML odf format. Is this a good idea?

  • Git stores snapshots of files rather than diffs, so it doesn't really matter how much the file changes. More important is overall file size, because those files have to be replicated on each clone. – kdgregory May 6 '17 at 14:55
  • 1
    I don't think that this is correct git-scm.com/book/en/v2/Git-Internals-Packfiles – mcocdawc May 6 '17 at 15:33
  • 1
    That depends on your viewpoint. The logical object storage format is a full file per revision. The physical storage format (and the network transfer format) is a pack file. In both cases, it is irrelevant whether the file is binary or text, in fact, Git's storage layer doesn't even care about content at all. – Jörg W Mittag May 6 '17 at 16:09

For generic vector graphics, SVG is the way to go.

For more specific uses, there are sometimes more specific languages available. For example, the OMG specifies a full XML representation for UML, so if your vector graphics are actually UML diagrams, you could use that instead. Or, even better yet, there are various plaintext languages for certain subsets of certain UML diagrams, for example PlantUML or yUML (Note: yUML is a webservice which encodes the plaintext description of the diagram in the URI and serves back a graphic; that's not what you want, but the language yUML uses could be re-used within text files as well.) Check out this list of textual UML languages.

For graphs, there is the mighty and venerable DOT language. Many tools understand DOT, the original implementation is GraphViz.

The DiagrammR web service doesn't exist anymore, but the library is still on GitHub.

In general, there are two approaches:

  • describe the diagram on a high-level, then generate a graphic from that description
  • draw the diagram as ASCII-art, then convert the ASCII-art to a graphic form

You probably want the former, not the latter. The only advantage the latter has over binary files is that you can look at them in a text editor. But merging and diffing is probably going to be just as useless, since all those tools are line-based and ASCII-art is 2-dimensional. The former are more like programming languages: one concept == one line.

If minor changes occur, the file change should be minor as well.

Git logically always stores a snapshot of the entire file per revision, regardless of whether the file is binary or text. (In fact, Git doesn't care about the contents of files at all, so the very concept of "text" or "binary" is fundamentally meaningless.)

The physical storage format are so-called "pack files". In pack files, the entire repository (i.e. all files from all revisions) are concatenated into a single file, and delta-compression is applied to the entire pack, i.e. Git (intelligently) looks for similarities in different revisions of the same file, different files in the same revision, different files across different revisions, and really pretty much anywhere, and efficiently compresses those.

Again, it does not matter for this whether the file is binary or text. It does matter whether you are using a format where small changes to the abstract content result in large changes to the serialized byte stream. That would indeed be in-efficient. An (imaginary) example would be a PDF file: PDF files usually contain compressed content, but they don't have to, and in Git, it would actually be more space-efficient to use uncompressed PDFs, because then the packer could detect the similarities between two revisions. Whereas when the contents are compressed, the compressed bytestream will often look completely different even if there are only small changes to the actual content.

  • Wow, thank you very much for this precise and exhaustive answer. – mcocdawc May 6 '17 at 16:37
  • 1
    "For graphs, there is the mighty and venerable DOT language." And, if you really want your documentation to look like a 90s CS research paper, you should go the whole hog and typeset it with LaTeX. – Jules May 6 '17 at 18:34
  • @Jules I typeset my resume in LaTeX - works pretty well, and looks a lot nicer than the resumes headhunters give me... so what would you say modern CS research papers are written in, markdown? – Aaron Hall May 8 '17 at 19:02

The SVG format is a well known, widely accepted vectorial format. It's XML-based, so it's Git friendly. SVG is an open standard supported by the W3C consortium.

SVG meets the criteria you need.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.