git2rss

#!/usr/bin/env perl
#
# git2rss
# John Simpson <jms1@jms1.net> 2023-07-25
#
# Generate an RSS feed from the commits in the current branch in a git repo
#
# 2023-07-29 jms1 - added command line options so that configuration can be
#   done from the command line *or* from a config file, also removed option
#   to specify a branch (make sure the directory has the correct branch
#   checked out first)
#
# 2025-01-12 jms1 - removed `-w` from shebang line. Some 'env' programs don't
#   support options on the shebang line without extra options, and other 'env'
#   programs don't have those options. The "lowest common denominator" is to
#   not have extra options at all, which in this case is okay because the
#   `use warnings` pragma does the same thing as the `-w` option anyway.
#   Thanks to Github user 'jake-47` for pointing this out.
#
###############################################################################
#
# MIT License
#
# Copyright (c) 2023-2025 John Simpson
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
###############################################################################

require 5.005 ;
use strict ;
use warnings ;

use File::Temp qw( tempdir ) ;
use Getopt::Std ;
use POSIX qw ( strftime ) ;

########################################
# getopts

my %opt             = () ;
my $do_debug        = 0 ;       # -d    debug messages
my $title           = '' ;      # -t:   feed title
my $link            = '' ;      # -l:   feed link
my $description     = '' ;      # -d:   feed description
my $image_url       = '' ;      # -i:   feed image URL
my $show_email      = '' ;      # -e:   how to show emails (full, name, none)
my $commit_url      = '' ;      # -c:   URL for individual commit
my $limit           = 0 ;       # -n:   number of commits, 0=show all
my $only_opt        = 0 ;       # -o    only look at command line options

###############################################################################
#
# usage

sub usage(;$)
{
    my $msg = ( shift || '' ) ;

    print <<EOF ;
$0 [options] [DIR]

Generate an RSS feed from a git repository's commit history.

If DIR is not specified, the current directory will be used. The directory
must be a cloned copy of a git repo, with the branch whose history is being
reported, already checked out.

The feed itself can be configured using command line options, OR using a
config file called '.git2rss' in the root directory of the repo. Command
line options will override a config file.

Feed configuration

-t ___  title=___       Feed title (required)

-l ___  link=___        URL for feed as a whole (required)

-d ___  description=___ Short description of the feed (required)

-i ___  image_url=___   URL of image for feed as a whole (optional)

-e ___  show_email=___  How to show email addresses in the commit messages
                        - full   Show full email address
                        - name   Only show name (before '@')
                        - none   Don't show email at all (default)

-c ___  commit_url=___  URL for each commit.
                        - Any '%s' will be replaced with the commit hash.

-n ___  limit=___       How many commits to include in the feed. If zero or
                          not specified, all commits will be included.

Other options

-o      Only check command line options, ignore any '.git2rss' file.

-d      Show debug messages.

-h      Show this help message.

EOF

    if ( $msg ne '' )
    {
        print $msg ;
        exit 1 ;
    }

    exit 0
}

###############################################################################
#
# debug

sub debug(@)
{
    $do_debug && print @_ ;
}

###############################################################################
#
# Parse an INI-style config file

sub parse_config_ini($)
{
    my $filename    = shift ;
    my %rv          = () ;

    open( C , '<' , $filename )
        or die "ERROR: can't read \"$filename\": $!\n" ;

    my $section = '' ;

    while ( my $line = <C> )
    {
        ########################################
        # Trim whitespace and comments, ignore otherwise empty lines

        $line =~ s|\s+$|| ;
        $line =~ s|^\s*#.*|| ;
        next unless ( $line ne '' ) ;

        ########################################
        # If this line starts a section, remember the section name

        if ( $line =~ m|^\[(.*?)\]| )
        {
            $section = $1 ;
        }

        ########################################
        # If this line is a "key=value" line, parse and remember it

        elsif ( $line =~ m|^\s*(\S+)\s*\=\s*(.*)$| )
        {
            my ( $k , $v ) = ( $1 , $2 ) ;

            if ( $section ne '' )
            {
                $k = lc( "$section.$k" ) ;
            }

            if ( $v =~ m|^"(.*?)"| )
            {
                $v = $1 ;
            }

            $rv{$k} = $v ;
        }
    }

    close C ;

    return %rv ;
}

###############################################################################
#
# Make a value safe for use in "HTML within XML"

sub sanitize($)
{
    my $x = shift ;

    $x =~ s|&|&amp;amp;|g ;
    $x =~ s|<|&amp;lt;|g ;
    $x =~ s|>|&amp;gt;|g ;

    return $x ;
}

###############################################################################
#
# Read commits into memory

sub read_commits($$$)
{
    my $dir         = shift ;
    my $limit       = shift ;
    my $show_email  = shift ;

    ########################################
    # Info about the commits we're reading

    my %commit  = () ;      # hash => { attributes each commit }
    my @cseq    = () ;      # sequence commit hashes were printed

    ########################################
    # Build "author" format string

    my $aformat = ':author: %an%n' ;
    if ( $show_email eq 'full' )
    {
        $aformat = ':author: %an <%aE>%n' ;
    }
    elsif ( $show_email eq 'user' )
    {
        $aformat = ':author: %an <%aL>%n' ;
    }

    ############################################################
    # Run the command

    my $lopt = $limit ? "-n $limit" : '' ;

    my $log_cmd = "( cd \"$dir\" && "
        . "git log $lopt"
        . ' --no-abbrev-commit'
        . ' --no-show-signature'
        . ' --name-status'
        . ' --format=format:":commit: %H%n'
            . ':date: %at %aD%n'
            . $aformat
            . ':subject: %s%n'
            . ':body: %b%n'
            . ':files:"'
        . " )" ;

    debug "\$log_cmd=\"$log_cmd\"\n" ;

    open ( I , "$log_cmd |" )
        or die "$log_cmd\nERROR: $!\n" ;

    ########################################
    # Process the commits

    my $the_commit  = '' ;
    my $the_t       = 0  ;
    my $the_date    = '' ;
    my $the_author  = '' ;
    my $the_email   = '' ;
    my $the_subject = '' ;
    my $the_body    = '' ;
    my $the_files   = '' ;

    my $in_body     = 0 ;
    my $in_files    = 0 ;

    while ( my $line = <I> )
    {
        debug "LINE \"$line\"\n" ;

        $line =~ s|\s+$|| ;

        if ( $line =~ m|^:commit: (\S+)| )
        {
            my $this_commit = $1 ;

            if ( $the_commit ne '' )
            {
                ########################################
                # Trim any extra blank lines from the end of body/files

                $the_body   =~ s|\s+$||s ;
                $the_files  =~ s|\s+$||s ;

                ########################################
                # Remember this commit's info

                push( @cseq , $the_commit ) ;
                $commit{$the_commit}->{'t'      } = $the_t       ;
                $commit{$the_commit}->{'date'   } = $the_date    ;
                $commit{$the_commit}->{'author' } = $the_author  ;
                $commit{$the_commit}->{'email'  } = $the_email   ;
                $commit{$the_commit}->{'subject'} = $the_subject ;
                $commit{$the_commit}->{'body'   } = $the_body    ;
                $commit{$the_commit}->{'files'  } = $the_files   ;
            }

            ########################################
            # Start remembering the new commit

            $the_commit  = $this_commit ;
            $the_t       = 0  ;
            $the_date    = '' ;
            $the_author  = '' ;
            $the_email   = '' ;
            $the_subject = '' ;
            $the_body    = '' ;
            $the_files   = '' ;
            $in_body     = 0 ;
            $in_files    = 0 ;
        }
        elsif ( $line =~ m|^:date: (\d+) (.+)$| )
        {
            ( $the_t , $the_date ) = ( $1 , $2 ) ;
        }
        elsif ( $line =~ m|^:author: (.+) <(.*)>$| )
        {
            ( $the_author , $the_email ) = ( $1 , $2 ) ;
        }
        elsif ( $line =~ m|^:author: (.+)$| )
        {
            $the_author = $1 ;
        }
        elsif ( $line =~ m|^:subject: (.+)$| )
        {
            $the_subject = $1 ;
        }
        elsif ( $line =~ m|^:body: (.+)$| )
        {
            $the_body   = $1 ;
            $in_body    = 1 ;
            $in_files   = 0 ;
        }
        elsif ( $line =~ m|^:files:$| )
        {
            $in_body    = 0 ;
            $in_files   = 1 ;
        }
        elsif ( $in_body )
        {
            $the_body   .= "\n$line" ;
        }
        elsif ( $in_files )
        {
            $the_files   .= "$line\n" ;
        }
    }

    ########################################
    # Make sure the last commit is processed

    if ( $the_commit ne '' )
    {
        ########################################
        # Trim any extra blank lines from the end of body/files

        $the_body   =~ s|\s+$||s ;
        $the_files  =~ s|\s+$||s ;

        ########################################
        # Remember this commit's info

        push( @cseq , $the_commit ) ;
        $commit{$the_commit}->{'t'      } = $the_t       ;
        $commit{$the_commit}->{'date'   } = $the_date    ;
        $commit{$the_commit}->{'author' } = $the_author  ;
        $commit{$the_commit}->{'email'  } = $the_email   ;
        $commit{$the_commit}->{'subject'} = $the_subject ;
        $commit{$the_commit}->{'body'   } = $the_body    ;
        $commit{$the_commit}->{'files'  } = $the_files   ;
    }

    ########################################
    # Finished

    close I ;

    $commit{''} = join( ':' , @cseq ) ;

    return %commit ;
}

###############################################################################
###############################################################################
###############################################################################

getopts( 'hDt:l:d:i:e:c:n:o' , \%opt ) ;
$opt{'h'} && usage() ;
$do_debug   = ( $opt{'D'} ? 1 : 0 ) ;
$only_opt   = ( $opt{'o'} ? 1 : 0 ) ;

my $dir     = ( shift || '.' ) ;

########################################
# Find the root of the git repo

my $cmd = "( cd \"$dir\" ; git rev-parse --show-toplevel )" ;
open( I , "$cmd |" )
    or die "ERROR: $cmd: $!\n" ;
my $repo_dir = <I> ;
close I ;

chomp $repo_dir ;

debug "\$repo_dir='$repo_dir'\n" ;

########################################
# read .git2rss file (if it exists)
# - not all RSS Feed attributes are supported
#   https://www.rssboard.org/rss-specification

my %config = () ;

unless( $only_opt )
{
    if ( -f "$repo_dir/.git2rss" )
    {
        %config = parse_config_ini( "$repo_dir/.git2rss" ) ;
    }
}

########################################
# Figure out the config values

$title          = ( defined $opt{'t'} ) ? $opt{'t'} : ( $config{'title'      } || '' ) ;
$link           = ( defined $opt{'l'} ) ? $opt{'l'} : ( $config{'link'       } || '' ) ;
$description    = ( defined $opt{'d'} ) ? $opt{'d'} : ( $config{'description'} || '' ) ;
$image_url      = ( defined $opt{'i'} ) ? $opt{'i'} : ( $config{'image_url'  } || '' ) ;
$show_email     = ( defined $opt{'e'} ) ? $opt{'e'} : ( $config{'show_email' } || '' ) ;
$commit_url     = ( defined $opt{'c'} ) ? $opt{'c'} : ( $config{'commit_url' } || '' ) ;
$limit          = ( defined $opt{'n'} ) ? $opt{'n'} : ( $config{'limit'      } || 0  ) ;

########################################
# Make sure the required values are present

my $err = 0 ;
if ( $title eq '' )
{
    print "ERROR: title (-t) not specified\n" ;
    $err ++ ;
}

if ( $link eq '' )
{
    print "ERROR: link (-l) not specified\n" ;
    $err ++ ;
}

if ( $description eq '' )
{
    print "ERROR: description (-d) not specified\n" ;
    $err ++ ;
}

if ( $commit_url ne '' )
{
    if ( $commit_url !~ m|%s| )
    {
        print "ERROR: commit_url (-c_ does not contain '%s'\n" ;
        $err ++ ;
    }
}

if ( $limit !~ m|^\d+$| )
{
    print "ERROR: invalid limit (-n) value\n" ;
    $err ++ ;
}

if ( $err )
{
    die "cannot continue\n" ;
}

###############################################################################
#
# Read commit info into memory

my %commit = read_commits( $repo_dir , $limit , $show_email ) ;

my @cseq = split( /:/ , $commit{''} ) ;
delete $commit{''} ;

########################################
# Get timestamp of most recent commit
# - this becomes the pubDate attribute of the feed

my $max_t   = 0 ;
my $pubDate = '' ;

for my $c ( keys %commit )
{
    if ( $commit{$c}->{'t'} > $max_t )
    {
        $max_t      = $commit{$c}->{'t'} ;
        $pubDate    = $commit{$c}->{'date'} ;
    }
}

########################################
# Get current date/time

$ENV{'TZ'} = 'UTC' ;
my $lastBuildDate = strftime( '%a, %d %b %Y %H:%M:%S %z' , gmtime() ) ;

###############################################################################
#
# Write RSS file

print <<EOF ;
<?xml version="1.0"?>
<rss version="2.0">
  <channel>
    <title>$title</title>
    <link>$link</link>
    <description>$description</description>
    <pubDate>$pubDate</pubDate>
    <lastBuildDate>$lastBuildDate</lastBuildDate>
EOF

for my $c ( @cseq )
{
    my $title       = sanitize( $commit{$c}->{'subject'} ) ;
    my $author      = sanitize( $commit{$c}->{'author'}  ) ;
    my $email       = sanitize( $commit{$c}->{'email'}   ) ;
    my $pubDate     = sanitize( $commit{$c}->{'date'}    ) ;
    my $body        = sanitize( $commit{$c}->{'body'}    ) ;
    my $files       = sanitize( $commit{$c}->{'files'}   ) ;

    my $bf = ( $body ne '' ) ? "$body\n\n" : '' ;
    $bf .= $files ;

    my $aline = "Author: $author"
        . ( ( $email ne '' ) ? " &amp;lt;$email&amp;gt;" : '' ) ;

    print <<EOF ;
    <item>
      <guid>$c</guid>
      <pubDate>$pubDate</pubDate>
EOF

    if ( $commit_url ne '' )
    {
        my $url = sprintf( $commit_url , $c ) ;

        print <<EOF ;
      <link>$url</link>
EOF
    }

    print <<EOF ;
      <title>$title</title>
      <author>$author</author>
      <description>
        <pre>Commit: $c
$aline
Date: $pubDate

$title

$bf</pre>
      </description>
    </item>
EOF
}

print <<EOF ;
  </channel>
</rss>
EOF