Git metadata preprocessor

[danyill]

Re-did this using rugged as per your fine suggestions. This also solved the problem of locating the repository as rugged allows this to occur from an arbitrary location.

Probably there is a large number of potential attributes one might want. I chose some of the more immediately obvious ones.

Many thanks for your help with this.

[ggrossetie]

Overall this is really good! 👍

[danyill]

thanks for your comments @Mogztter, much appreciated

[ilvetz]

Tried testing this extension but I can't get a working rugged gem on Windows.

[danyill]

Yes, it looks like something of a challenge.

I haven't tried but:

http://matt.scharley.me/2016/01/rugged-windows.html

Perhaps more simpler, rubyinstaller2 may do the trick out of the box:

https://github.com/libgit2/rugged/issues/669

On Thu, Sep 28, 2017 at 3:17 AM, Michele Vetturi notifications@github.com wrote:

Tried testing this extension but I can't get a working rugged gem on Windows.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/asciidoctor/asciidoctor-extensions-lab/pull/79#issuecomment-332536096, or mute the thread https://github.com/notifications/unsubscribe-auth/AApL3xwFPdw_LPI-qmg4-gdIIXD545FJks5smlkQgaJpZM4PhIWS .

--

-- Private or confidential message? Public Key available here https://pgp.mit.edu/pks/lookup?search=dan.mulholland%40gmail.com&op=index :

[danyill]

@Mogztter I've added some extra fields and improved the branch handling. I think I'm about done but happy for further reviews. I'd be delighted to see this PR merged at some stage.

In particular, I think a relative path to the root repository is a useful attribute. I often need this to locate centralised information (css, js etc) for when I have several Asciidoc files in a repository and don't want to duplicate particular assets. It is annoying to hard code it.

I also modified so we didn't set attributes for e.g. tags or the origin remote if they are not present. I think the other fields should always be present in a repo which is not empty but there's bound to be some other case I haven't thought about.

[mojavelinux]

@danyill You've done an incredible job on this extension. I'm going to review and merge it as soon as I get a chance, hopefully this week.

[danyill]

@mojavelinux https://github.com/mojavelinux thanks - no hurry. I updated the sample document this morning to make it hopefully more helpful and also realised that my attribute for checking tags against the current commit is only working for lightweight tags and I think it should also do annotated tags so I'll have another look at that soon.

On Mon, Oct 2, 2017 at 7:47 PM, Dan Allen notifications@github.com wrote:

@danyill https://github.com/danyill You've done an incredible job on this extension. I'm going to review and merge it as soon as I get a chance, hopefully this week.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/asciidoctor/asciidoctor-extensions-lab/pull/79#issuecomment-333452943, or mute the thread https://github.com/notifications/unsubscribe-auth/AApL3-0JF4vaxjUS-LLZookTVrh1rrY_ks5soIb6gaJpZM4PhIWS .

--

-- Private or confidential message? Public Key available here https://pgp.mit.edu/pks/lookup?search=dan.mulholland%40gmail.com&op=index :

[mojavelinux]

I tried it and it works great. I'm going to commit, then follow up with a few stylistic changes that trim a few superfluous characters.

The only suggestion that comes to my mind is to use the git- prefix instead of git-metadata. I think that git- is unique enough that it wouldn't collide. If it did, perhaps it can be a configurable setting.

[mojavelinux]

I'm done applying the code formatting. I found a few ways to trim some characters. In particular, the tag processing could be reduced to:

tags = repo.tags
    .select {|t| t.target_id == head.target_id || (t.annotated? && t.annotation.target_id == head.target_id) }
    .map(&:name)
doc_attrs['git-metadata-tag'] = tags * ', ' unless tags.empty?

[danyill]

Thank you @mojavelinux

I appreciate your comments and hope people find this useful.

I chose the name git-metadata because I can see a need for a range of git-based extensions. However it is a bit long and you're more than welcome to change it.

Some other useful extensions might be:

• Changelog generation -- In my changelog, for each new release I expect I would like to be able to generate into the Asciidoc a list of commits (we discussed elsewhere and at the moment this is too hard for me to progress). For extra coolness, processing them using semantic commit messages or similar would be helpful (https://seesparkbox.com/found ry/semantic_commit_messages). I had a look at https://gitlab.com/sue445/ gitlab_awesome_release and will (eventually) try and build something with this.

• Extraction of git data by user query -- a git macro which picked up useful attributes (e.g. for a given tag as a parameter return the date/time and tagger name) would be of assistance.

• Automated diffs based on git commit reference -- I am presently producing automated diffs with previous versions using (really) nasty bash and the python package htmldiff which produces quite a good "Word-like tracked changes" with the default backend. I think it would be really neat to have some kind of processor which said for a given backend (easy for html) create two documents, then post-process to find the differences. Perhaps that should righteously be an external tool and not an Asciidoctor extension? I suspect this is a common use case which many people would like a solution to. I guess how this might ideally work is we set an attribute in the document (e.g. git-diff-show) and an attribute diff-reference and then our output document is automatically the "tracked changes" version.

On Wed, Oct 4, 2017 at 7:47 PM, Dan Allen notifications@github.com wrote:

I'm done applying the code formatting. I found a few ways to trim some characters. In particular, the tag processing could be reduced to:

tags = repo.tags .select {|t| t.target_id == head.target_id || (t.annotated? && t.annotation.target_id == head.target_id) } .map(&:name) doc_attrs['git-metadata-tag'] = tags * ', ' unless tags.empty?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/asciidoctor/asciidoctor-extensions-lab/pull/79#issuecomment-334064487, or mute the thread https://github.com/notifications/unsubscribe-auth/AApL33LlYWPUr22PoTttI0QdOtIPR95Mks5soynxgaJpZM4PhIWS .

--

-- Private or confidential message? Public Key available here https://pgp.mit.edu/pks/lookup?search=dan.mulholland%40gmail.com&op=index :

[mojavelinux]

@danyill These are great ideas. Thanks for sharing.

I could definitely see this extension evolving into its own project. I think it make sense to incubate it here, but eventually it will need it's own space to grow. Graduating it to a project also makes it possible to distribute it as a gem.

[danyill]

@ilvetz

It is a trick installing the rugged gem. Although it depends on your approach, my initial approach was poor...

Initially I tried to do it from x86 rubyinstaller2 package for Ruby 2.4 with half a day wasted and a lot of messing about with cmake and pkg-config and libssh2. Then I thought "Why am I using the x86 package?".

So. Installing rugged on a fresh Windows 7 Pro VM is quite easy as I found with the Ruby 2.4 x64 installer. (BTW These instructions are mainly meant for my staff, not trying to tell you how to suck eggs). We need to install an up-to-date libgit2 since the bundled version in MSys is too old and we need to build from source.

Blow-by-blow:

1. Run the rubyinstaller2 package, rubyinstaller-2.4.2-2-x64.exe using the defaults and with the following guidance...
2. Select UTF-8 as the base encoding when prompted as shown below:
3. When prompted by the funny pixellated Ruby Installer 2 for Windows, just press Enter.
4. Don't run Msys (leave unchecked and click Finish).
5. When prompted again by the installer just press Enter and it will exit.
6. Go to Start > Run and enter cmd and then in the command shell:
   • ridk exec pacman -S mingw-w64-x86_64-libgit2
   • gem install rugged --platform ruby -- --use-system-libraries

This should end saying the gem is installed correctly.

A few notes:

1. I read some reports about the Rubyinstaller2 looking in the wrong place during Mingw/MSYS installation if Git was installed (which has an inadequate version of mingw). I suggest you chop anything unnecessary out of your path if these commands don't "just work". I haven't tried to independently verify this problem/solution.
2. I doubt these instructions are necessarily valid for Ruby 2.3 or earlier as the installer and dev tools mechanisms have been substantively changed.
3. I suspect the libgit2 package should be pinned as rugged only supports some versions of libgit2. But today, at least it works :smile_cat:

To test the extension:

git clone https://github.com/asciidoctor/asciidoctor-extensions-lab/
cd asciidoctor-extensions-lab
asciidoctor -r .\lib\git-metadata-preprocessor.rb .\lib\git-metadata-preprocessor\sample.adoc

And then try opening sample.html in the preprocessor folder.

Let us know if this helps.

[mojavelinux]

Wow, that is great material.

You might want to consider putting this in a gist (or some other ad-hoc publishing location) and linking to it from the extension file. If this extension graduates to a separate project, then the contents of that gist could get pulled into the documentation.