1. 12
  1.  

  2. 3

    I recommend having a look at http://keepachangelog.com/en/1.0.0/ and seeing if you can apply any of the advice - a changelog is most useful when it’s curated with the users in mind. Users tend not to want to read about whitespace being removed, for example - if they did, i think they would just read git log!

    1. 2

      Well I have both: a release announcment where I summarized changes, and the raw git log.

      http://www.oilshell.org/blog/2017/09/09.html#appendix-b

      The hyperlinks in the HTML git log are what help me write the human-readable version!

      1. 1

        Ah, excellent!

    2. 3

      I think, personally, I would solve this by calling git log twice, and joining the inputs. Nowhere near as clean, but easier to escape (no special characters).

      I would love to see how to solve this with OSH, as an extension of this post. Seeing a real problem that I can empathise with concretely, and then having “OSH will fix this ;)” feels like a tease!

      1. 3

        If I’m understanding you correctly, I think the joining solution is a little fragile with respect to:

        1. Inputs with multiple lines. What if I wanted the full git commit description and not just the first line?
        2. If there are 4 fields, which there are in the real problem, then you need 4 invocations of git log. Or at least you need an invocation per field that contains spaces.

        Also I’ve used the “join” or “paste” commands and I honestly find them very difficult.

        As for Oil, that’s unfortunately a little far off (hence the call for help in the post!). OSH is the bash clone, so you will solve it the same way as bash.

        Oil is the new language, and one improvement is would be a way to store structured data in memory! In particular, tables!

        I’ve summarized some notes here:

        https://github.com/oilshell/oil/wiki/Oil-and-the-R-Language

        The slogan is that “the output of ls and ps are tables”. And the output of git log is a table. So Oil will be able to parse arbitrary data and store the “correct” values in memory. Then it can serialize them to any output format. So bash has the paradigm:

        $ input | process text in a hacky and probably incorrect way | output
        

        Oil will still allow that. You can play fast and loose if you want. But it will also allow:

        $ input | properly deserialized | structured data | properly serialize | output
        
        1. 2

          I also thought of @dominicm’s solution, but you’re right, that solution has problems.

          The simplest solution I can think of, while being obviously safe against adversarial input, would be a script in a scripting language. The key improvement over “the pedantic solution” in the blog post is that you don’t actually need a Git API. You just need a language that can easily call system commands. What’s more, you can fetch the information for just one commit at a time with something like git log HEAD~3 -n 1, which avoids having to stitch together git log’s output for multiple commits.

          Using those ideas, here is how I would do it in Ruby, calling out to Git with system:

          #!/usr/bin/env ruby
          require 'cgi'
          
          def escaped_git_log_part(commits_back_from_head, format)
            log_output = system "git log HEAD~#{commits_back_from_head} " +
              "-n 1 --pretty='format:#{format}'"
            CGI.escapeHTML(log_output)
          end
          
          puts '<table>'
          0.downto(4).each do |commits_back|
            part_H = escaped_git_log_part(commits_back, '%H')
            part_h = escaped_git_log_part(commits_back, '%h')
            part_s = escaped_git_log_part(commits_back, '%s')
            puts "<tr>
              <td> <a href='https://example.com/commit/#{part_H}'>#{part_h}</a> </td>
              <td>#{part_s}</td>
            </tr>"
          end
          puts '</table>'
          

          It’s kind of repetitive, but good enough for a safe but quick-to-write shell script, I think.

      2. 1

        Another example of “Unix-style” programming is generating plots with gnuplot. There are lots of great plotting libraries for languages like R and Python, but I’ve found that if you have some log files and quickly want to visualise some data, a single line of awk piped into gnuplot is often all you need.