Printing Git Versioning Info in a Score

Whenever working on a notation project of some extent you will run into the situation of having printouts of intermediate states of the score, for example to do proof-reading. And as soon as there are more than one of these printouts you will have to take care tagging them appropriately in order to know which state of development they represent. As I’ve written over and over in this place version control can become an indispensable tool for not getting lost in project development. So why not just integrate the two approaches and print version control information directly on the score?

We’ve been discussing this idea on several levels for quite some time. For example it would be nice to be able to integrate Git information in the metadata of the PDF files or in the resulting file name. And it would be nice to have tools in editors like Frescobaldi to handle versioned scores and offer graphical approaches to comparing them. Well, all this hasn’t been achieved or even thought through to the end, but thanks to a comment to an earlier post of me by Lars Haulin I was now able to implement a way to print relevant information with LilyPond directly, for example in the tagline.

I have added a snippet to our openLilyLib snippets repository which can be found in the editorial-tools/git-commands directory. Currently it provides a number of markup commands printing

  • \gitCommittish
    the short version of the Git committish
  • \gitCommit
    the oneline commit message of the latest commit
  • \gitDateTime
    the date of the last commit
  • \gitAuthor and \gitEmail
    info about the author of the last commit
  • the committish and oneline message of the parent commit
  • gitBranch
    the branch we’re currently on
  • gitRevisionNumber
    the number of commits that lead to the current commit

An additional Scheme function gitIsClean determines if there are changes to the repository on top of the latest commit. Of course this is important information because often one would rather create a commit after doing the printout – and in that case the reference to the latest commit doesn’t really tell the truth about the state of the score. As I didn’t want to prescribe how such information is presented this function simply returns a boolean value and the user has to provide a markup on her own.

In addition there are more “verbose” commands that return multiline text, currently \gitFullCommit and \gitDiff. These can also provide interesting state information but should usually be printed on separate pages or even a dedicated bookpart, otherwise they would severely disturb the score layout.

As the snippet provides the generic markup command \gitCommand it is quite easy to add custom command for your specific needs.

Click to view fullpage example PDF

Click to view fullpage example PDF

Have a look at the attached example document to get a better idea of what is possible.
Or download the two files definitions.ily and example.ly, save it beside one another within a Git repository and compile the .ly file.
As usual, any suggestions are welcome.

10 thoughts on “Printing Git Versioning Info in a Score

  1. Reedmace Star

    My favourite git revision annotation is the output of “git describe”, which includes the most recent tag and the number of commits since. The piece of code I have been using for some time now will try, in this order, git describe master, git describe --tags master and git log -1 --pretty=format:%H, and use the output of the first command that works (or #(strftime "%Y-%m-%dT%H%M%S%z" (gmtime (current-time))) if none does).

    Reply
    1. Reedmace Star

      Actually, re-checking the git-describe man page right now suggests that this can be simplified by using the options --dirty and --always. Either I overlooked them when assembling my code, or they are new.

      Reply
      1. Gregrs

        I have also been using Git with LilyPond (on an Ubuntu PC) for some time now after reading something else that Urs wrote on the subject. (Having experimented with a few GUIs, I have ended up just using gitk, git gui and occasionally the command line.)

        Like Reedmace Star, I use ‘git describe –tags –dirty –always’ as a revision identifier. I had been implementing this using a hook script, but using \gitCommand is much more elegant so thank you!

        I generally create a tag with the date (e.g. 2014-10-29) for each major revision, for example if I print out a whole score or email it to somebody. The above command then describes the version using just this date tag. If I create more commits after this, the tag shows the latest major revision, latest commit and number of commits since the latest major revision (i.e. latest tag). I’ve pasted the header code I use below in case it’s of any use to anyone:

        oddHeaderMarkup = \markup {
          \fill-line {
            \line{}
            \line{\small {"My Piece – rev." \gitCommand "describe --tags --dirty --always"}}
            \line{
              \on-the-fly #print-page-number-check-first
              \fromproperty #'page:page-number-string
            }
          }
        }
        evenHeaderMarkup = \markup {
          \fill-line {
            \line{
              \on-the-fly #print-page-number-check-first
              \fromproperty #'page:page-number-string
            }
            \line{\small {"My Piece – rev." \gitCommand "describe --tags --dirty --always"}}
            \line{}
          }
        }
        Reply
  2. Henning

    I only know very little about git, but is it correct that — as far as I see — in definitions.ily and in the example.pdf gitCommitish ist exactly the same as gitParentCommitish and gitCommit the same as gitParentCommit?

    Reply
    1. Urs Liska

      Good catch, I don’t know how this could have happened.
      I have updated the files (make sure you reload the browser because the old versions are probably cached). Practically you can see the difference in the “full diff” on page two 😉

      Reply
  3. Janek Warchoł

    I suggest to also add a command for
    git log --format="%h %< (18,trunc)%ci%x08%x08 %<(60,trunc)%s" -1

    This prints committish, commit date (formatted a bit so that it's not too long) and commit summary truncated to 60 characters. Personally i think that this is just the information one needs - author name is usually not important, while date with time helps a lot with ordering of printouts.

    Also note that i have used the commit date instead of author date - this is because author date isn't updated when the commit is modified (for example amended or rebased), while commit date is. In other words, commit date more accurately shows when the score was modified.

    Reply
    1. Urs Liska

      Could you please recheck if the displayed command is what you intended (so the WP editors don’t break anything)? When I try out that command it see the %< (18,trunc) parts in the result literally.

      Reply
      1. Janek Warchoł

        Oops, i didn’t noice your reply. Indeed, there shouldn’t be a space before (18,trunc).
        git log --format="%h %< (18,trunc)%ci%x08%x08 %<(60,trunc)%s" -1

        EDIT: seems that WordPress is inserting additional space anyway... Hopefully the description will help!
        The strangest thing is that the second trunc is displayed correctly.

        Reply
  4. Lars Haulin

    Urs, you have made a wonderful work at making that small hack available to others! This made me happy. 🙂 Sorry for not giving better function descriptions back in that comment. I use my original version of the hack to show the version in the footer of every page of my music sheets.

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *