RepoSense can generate interactive visualizations of programmer activities, even across multiple repositories. It's ideal for educators and managers to get insights into the programming activities of their mentees. The visualizations can be easily shared with others (e.g., as an online dashboard), and updating the visualizations periodically can be automated.

Some example insights RepoSense can provide:

Insights about the code

• Which part of the code was written by Tom? How many lines? How many files?
• Which test cases were written by Kim?
• Which commit messages were written by Serene?

Insights about the type of work

• Which portion of Jacob's code is documentation?
• Who hasn't written any test code yet?
• Which project did Jolene contribute to in the last month?

Insights about the timing of work

• Who is putting in the consistent effort?
• Who waits till the deadline to do the work?
• Who hasn't started any work yet?

Insights based on comparisons

• Which programmers/teams are falling behind?
• How does everyone compare in their front-end coding work over the past two weeks?
• Who are the the top 10 code contributors?

Showcase

Case 1: Monitoring student programmers (individual projects)

• Scenario: RepoSense is used to monitor a Software Engineering course in which students build a project over 8 weeks.

• Links: report | repo containing the settings

• Example usages:

  • To compare students based on the amount of code written, we can sort by contribution, as done in this view.
  • This view shows us code written by a specific student.

Case 2: Monitoring student programmers (team projects)

• Scenario: Similar to case 1 above, but this time students are doing team projects.

• Links: report | settings

• Example usages:

  • To find the breakdown of the work done, we can tick the breakdown by file type checkbox, as shown in this view. After that, we can filter out certain file types by un-ticking the file type.
  • To find how teams compare in terms of total work done, we can tick the merge group check-box and sort groups by Contribution, as seen in this view. Also, note how i.e., each ramp represents the work done by the entire team in the whole weekthe granularity of the ramps is set to Week to reduce clutter.
  • This view shows the activities near the submission deadline (note how some have overshot the deadline and some others show a frenzy of activities very near to the deadline).

Case 3: Monitoring student programmers (multiple external projects)

• Scenario: Similar to cases 1 and 2 above, but this time, each student works on multiple projects. Furthermore, most projects are external OSS projects, not within the control of the teacher.

• Links: report | settings

• Example usages:

  • This view shows the commit messages written by a specific student.
  • Note how we can use the group by drop-down to organize activities around projects or individual authors.
  • Similarly, we can use the merge all groups check-box to see the sum of activities in a specific project or by a specific student.

Using reports

Viewing the report

As a report consists of web pages, it can be viewed using a Web Browser. Here are the ways to view the report in different situations.

• Situation 1: The report has been hosted on a website
  • Simply go to the URL of the report (example) in your browser.
• Situation 2: You generated the report in your computer earlier
  • Run RepoSense with the --view option:
    Format: java -jar RepoSense.jar --view REPORT_FOLDER
    e.g., java -jar RepoSense.jar --view ./myReport/reposense-report
• Situation 3: The report was given to you as a zip file or as a folder
  1. If it is a zip file, unzip it.
  2. Open the index.html (in the unzipped report directory) using a browser.
  3. If the report was not loaded automatically, click on the choose file button in the shown web page, and select the archive.zip (in the same directory) manually.
     If even the choose file button is not showing up, try a different browser.

Report structure

Here is an example of how a typical report looks like:

The report is divided into two sections: Chart panel and the Code panel. In some situations, the Commits panel will appear in place of the code panel. All three are explained in the sections below.

Chart panel

The Chart panel (an example is shown above) contains a series of ramp chart + contribution bar pairs, possibly organized into sub-groups, with a tool bar at the top.

Ramp charts

• The ramp's area is proportional to the amount of contribution the author made at that time period.
• The position of the right edge of the ramp (perpendicular to the blue bar) represents the period (the day or the week) in which the contribution was made.
• Hover the pointer over a ramp to see the total number of lines represented by that ramp.
• Click on the ramp to see on GitHub the list of commits represented by that ramp.
• To make the comparison between two authors easier, the color of the ramps that represent different authors' contributions at the same time period are the same.
• Ramps representing big contributions can overlap with earlier time periods. This represents the possibility that if the work committed during a specific period is big, it could have started at an earlier time period.

Contribution bars

• Hover over a contribution bar to see the exact amount of the contribution.
• If an author contributed significantly higher than other authors, the contribution bar could overflow into multiple lines.

Tool bar

The Tool Bar at the top of the Chart panel provides a set of configuration options that control the Chart panel.

• Search: filters the author and repository by keywords.
  • Multiple keywords/terms can be used, separated by spaces.
  • Entries that contain any (not necessarily all) of the search terms will be displayed.
  • The keywords used to filter the author and repository are case-insensitive.
• Group by: grouping criteria for the rows of results.
  • None: results will not be grouped in any particular way.
  • Repo/Branch: results will be grouped by repositories and its' associating branches.
  • Author: results will be grouped by the name of the author. Contributions made to multiple repositories by a particular author will be grouped under the author.
• Sort groups by: sorting criteria for the main group. See note [1] below.
  • Group title: groups will be sorted by the title of the group (in bold text) in alphabetical order.
  • Contribution: groups will be sorted by the combined contributions within a group, in the order of number of lines added.
  • Variance: groups will be sorted by how far the daily contributions are spread out from their average value among all authors involved. A detailed definition of variance is located here.
• Sort within groups by: sorting criteria within each group.
  • Title: each group will be internally sorted by it's title in alphabetical order.
  • Contribution: each group will be internally sorted by individual contributions in the order of number of lines added.
  • Variance: each group will be internally sorted by how far the daily contributions are spread out from their average value by each author into a particular repo. A detailed definition of variance is located here.
• Granularity: the period of time for which commits are aggregated in the Ramp Chart.
  • Commit: each commit made is shown as one ramp.
  • Day: commits within a day (commits made within 00:00 to 23:59) are shown as one ramp.
  • Week: commits within a week (from Monday 00:00 to Sunday 23:59) are shown as one ramp.
• Since, Until: the date range for the Ramp Chart (not applied to the Contribution Bars).
• Reset date range: resets the date range of the Ramp Chart to the default date range.
• Breakdown by file type: toggles the contribution bar to either display the bar by :
  • the total lines of codes added (if the checkbox is left unchecked), or
  • a breakdown of the number of lines of codes added to each file type (if the checkbox is checked). More info on note [3] below.
• Merge group: merges all the ramp charts of each group into a single ramp chart; aggregates the contribution of each group.
  • viewing of authored code of the group as a whole is available when group by repos.

Notes:
[1] Sort groups by: each main group has its own index and percentile according to its ranking position after sorting (e.g., if the groups are sorted by contribution in descending order, a 25% percentile indicates that the group is in the top 25% of the whole cohort in terms of contribution)
. [2] Repo/Branch: the repo/branch name is constructed as ORGANIZATION/REPOSITORY[BRANCH] (e.g., reposense/reposense[master])
[3] The total contribution of each group will get updated based on the checked file types and will be taken into account when the sorting criteria is contribution.

Code panel

The Code panel allows users to see the code attributed to a specific author. Click on the </> icon beside the author's name in the Chart panel to display the Code panel on the right.

• The Code panel shows the files that contain the author's contributions, sorted by the number of lines written.
• Select the radio button to enable one of the following 2 filters. Note that only 1 of the 2 filters is active at any time.
  • Type file path glob in glob filter to include files matching the glob expression.
  • Select the checkboxes to include files of preferred file extensions. The number right beside the file extension shows the total number of lines written by the author in such file extension files. In contrast, the number inside the parenthesis indicates the number of non-blank lines written by the author.
• Clicking the file title toggles the file content.
• Clicking the first icon beside the file title opens the history view of the file on GitHub.
• Clicking the second icon beside the file title opens the blame view of the file on GitHub.
• Code attributed to the author is highlighted in green.
• Non-trivial code segments that the selected author does not write are hidden by default, but you can toggle them by clicking on the icon.

Commits panel

The Commits panel allows users to see the commits attributed to a specific author.

• To view all commits attributed to an author, locate the author's ramp chart in the chart panel, and click on the icon above the ramp chart.
• To view commits of a specific period, locate the author's ramp chart in the chart panel, hold down the Ctrl key (⌘ in MacOS), and click on the start and end positions of the period (on the ramp chart) you want to view.
  

• The commits can be sorted by the date it was committed or by LoC.
• The tags of the commits will also be displayed on top if any. Clicking on a tag will direct you to the commit having that particular tag.
• The date range for the Chart panel can be updated by clicking on the "Show ramp chart for this period" below the name of the author.
• The ramp chart at the top of the Commits panel represents individual commits (not weekly or daily contributions).
• The commit messages body can be expanded or collapsed by clicking on the icon beside each commit message title.
• To promote and encourage the 50/72 rule for commit messages, a dotted vertical line will be shown for:
  • Commit message subject that exceeds 50 characters.
  • Commit message body after the 72nd character mark.

Generating a report

• If you have Java on your computer, the straight-forward way to generate a report is to use the RepoSense executable to generate the report locally on your computer, as explained in the Generating reports locally section below.

• If you don't have Java on your computer or do not wish to run the executable on your computer, some alternatives are provided in the Generating reports remotely section below.

Generating reports locally

1. Ensure you have the prerequisites:

   • Java 8 (JRE 1.8.0_60) or later (download ).
   • git 2.14 or later on the command line. (download ).
     run git --version in your OS terminal to confirm the version.

2. Download the latest JAR file from our releases.

3. Generate a report: The simplest use case for RepoSense is to generate a report for the recent history of a repo.
   command: java -jar RepoSense.jar --repos LIST_OF_REPO_URLS --view
   Examples:

   • java -jar RepoSense.jar --repos https://github.com/reposense/RepoSense.git --view (note the .git at the end of the repo URL)
   • java -jar RepoSense.jar --repos https://github.com/reposense/RepoSense.git c:/myRepose/foo/bar --view analyzes the two specified repos (one remote, one local).

   The above commands will analyze the given repo(s) for commits done within the last month and open the report in your default Browser.

To learn how to generate a report using e.g., generate a report for a different period, for specific file types, for specific authors, etc.other settings, head over to the Customizing reports section.

Generating reports remotely

You can generate a RepoSense report remotely without installing/running anything on your computer. This is particularly useful when you are deciding whether to adopt RepoSense.

The easiest option is to use Netlify. The instructions are given below.

You can also use the following options. While they are more work to set up, they are more suitable as a permanent solution due to their generous free tier.

{
  "ignoreGlobList": ["about-us/**", "**index.html"],
  "formats": ["html", "css"],
  "ignoreCommitList": ["90018e49f129ce7e0abdc8b18e91c9813588c601", "67890def", "abc123..def456"],
  "ignoreAuthorList": ["charlie"],
  "authors":
  [
    {
      "githubId": "alice",
      "emails": ["alice@example.com", "alicet@example.com"],
      "displayName": "Alice T.",
      "authorNames": ["AT", "A"],
      "ignoreGlobList": ["**.css"]
    },
    {
      "githubId": "bob"
    }
  ]
}

...
commit cd7f610e0becbdf331d5231887d8010a689f87c7
Author: ConfiguredAuthorName <author@example.com>
Date:   Fri Feb 9 19:14:41 2018 +0800

    Make some changes to show my new author's name

commit e3f699fd4ef128eebce98d5b4e5b3bb06a512f49
Author: ActualGitHubId <author@example.com>
Date:   Fri Feb 9 19:13:13 2018 +0800

    Initial commit
 ...

git config user.name

git config user.name "YOUR_AUTHOR_NAME”

git config --global user.name "YOUR_AUTHOR_NAME”

{
  "ignoreGlobList": ["about-us/**", "**index.html"],
  "formats": ["html", "css"],
  "ignoreCommitList": ["90018e49f129ce7e0abdc8b18e91c9813588c601", "67890def", "abc123..def456"],
  "ignoreAuthorList": ["charlie"],
  "authors":
  [
    {
      "githubId": "alice",
      "emails": ["alice@example.com", "alicet@example.com"],
      "displayName": "Alice T.",
      "authorNames": ["AT", "A"],
      "ignoreGlobList": ["**.css"]
    },
    {
      "githubId": "bob"
    }
  ]
}

...
commit cd7f610e0becbdf331d5231887d8010a689f87c7
Author: ConfiguredAuthorName <author@example.com>
Date:   Fri Feb 9 19:14:41 2018 +0800

    Make some changes to show my new author's name

commit e3f699fd4ef128eebce98d5b4e5b3bb06a512f49
Author: ActualGitHubId <author@example.com>
Date:   Fri Feb 9 19:13:13 2018 +0800

    Initial commit
 ...

git config user.name

git config user.name "YOUR_AUTHOR_NAME”

git config --global user.name "YOUR_AUTHOR_NAME”

Customizing reports

Customize using CLI flags

The simplest approach is to provide additional flags when running RepoSense. The various flags are given in the panel below.

Customize using CSV config files

Another, more powerful, way to customize the report is by using dedicated config files. In this case you need to use the --config flag instead of the --repo flag when running RepoSense, as follows:

Get target repos to provide more info

If feasible, you can also customize the target repos to play well with RepoSense in the following two ways:

1. Add a stand-alone config file to the repo to provide more config details to RepoSense. The format of the file is given below.

{
  "ignoreGlobList": ["about-us/**", "**index.html"],
  "formats": ["html", "css"],
  "ignoreCommitList": ["90018e49f129ce7e0abdc8b18e91c9813588c601", "67890def", "abc123..def456"],
  "ignoreAuthorList": ["charlie"],
  "authors":
  [
    {
      "githubId": "alice",
      "emails": ["alice@example.com", "alicet@example.com"],
      "displayName": "Alice T.",
      "authorNames": ["AT", "A"],
      "ignoreGlobList": ["**.css"]
    },
    {
      "githubId": "bob"
    }
  ]
}

...
commit cd7f610e0becbdf331d5231887d8010a689f87c7
Author: ConfiguredAuthorName <author@example.com>
Date:   Fri Feb 9 19:14:41 2018 +0800

    Make some changes to show my new author's name

commit e3f699fd4ef128eebce98d5b4e5b3bb06a512f49
Author: ActualGitHubId <author@example.com>
Date:   Fri Feb 9 19:13:13 2018 +0800

    Initial commit
 ...

git config user.name

git config user.name "YOUR_AUTHOR_NAME”

git config --global user.name "YOUR_AUTHOR_NAME”

2. To have more precise control over which code segment is attributed to which author, authors can annotate their code using @@author tags, as explained below.

Sharing reports

The sections below explain various ways of sharing a RepoSense report.

Share privately

To share a RepoSense report privately, simply find a way to share the folder containing the report (by default, it will be in a folder named reposense-report). For example, you can zip that folder and share it with the intended recipients.

You can point the recipients to the Using reports section for guidance on how to view reports.

Publish on the web

As RepoSense reports are in a web page format, you can publish a report by simply uploading it onto any web hosting service. Given below are several options that not only allow to publish reports, but also enable various levels of automating the entire process (e.g., automatically update the report daily).

{
  "ignoreGlobList": ["about-us/**", "**index.html"],
  "formats": ["html", "css"],
  "ignoreCommitList": ["90018e49f129ce7e0abdc8b18e91c9813588c601", "67890def", "abc123..def456"],
  "ignoreAuthorList": ["charlie"],
  "authors":
  [
    {
      "githubId": "alice",
      "emails": ["alice@example.com", "alicet@example.com"],
      "displayName": "Alice T.",
      "authorNames": ["AT", "A"],
      "ignoreGlobList": ["**.css"]
    },
    {
      "githubId": "bob"
    }
  ]
}

...
commit cd7f610e0becbdf331d5231887d8010a689f87c7
Author: ConfiguredAuthorName <author@example.com>
Date:   Fri Feb 9 19:14:41 2018 +0800

    Make some changes to show my new author's name

commit e3f699fd4ef128eebce98d5b4e5b3bb06a512f49
Author: ActualGitHubId <author@example.com>
Date:   Fri Feb 9 19:13:13 2018 +0800

    Initial commit
 ...

git config user.name

git config user.name "YOUR_AUTHOR_NAME”

git config --global user.name "YOUR_AUTHOR_NAME”

{
  "ignoreGlobList": ["about-us/**", "**index.html"],
  "formats": ["html", "css"],
  "ignoreCommitList": ["90018e49f129ce7e0abdc8b18e91c9813588c601", "67890def", "abc123..def456"],
  "ignoreAuthorList": ["charlie"],
  "authors":
  [
    {
      "githubId": "alice",
      "emails": ["alice@example.com", "alicet@example.com"],
      "displayName": "Alice T.",
      "authorNames": ["AT", "A"],
      "ignoreGlobList": ["**.css"]
    },
    {
      "githubId": "bob"
    }
  ]
}

...
commit cd7f610e0becbdf331d5231887d8010a689f87c7
Author: ConfiguredAuthorName <author@example.com>
Date:   Fri Feb 9 19:14:41 2018 +0800

    Make some changes to show my new author's name

commit e3f699fd4ef128eebce98d5b4e5b3bb06a512f49
Author: ActualGitHubId <author@example.com>
Date:   Fri Feb 9 19:13:13 2018 +0800

    Initial commit
 ...

git config user.name

git config user.name "YOUR_AUTHOR_NAME”

git config --global user.name "YOUR_AUTHOR_NAME”

Appendix: FAQ

Q: Does RepoSense work on private repositories?

A: RepoSense will first clone the git repository to be analyzed; thus, if you do not have access to the repository, we cannot run the analysis.
To enable RepoSense to work on private repositories, ensure that you have enabled access to your private repository in your git terminal first before running the analysis.

Q: How do formats work?

A: Formats are the file extensions, which is the suffix at the end of a filename that indicates what type of file it is.
The formats/file extensions to be analyzed by RepoSense can be specified through the standalone config file, repo-config file, and command line.

Q: How does ignore glob list work?

A: Glob is the pattern to specify a set of filenames with wildcard characters. Ignore glob list is the list of patterns to specify all the files in the repository which should be ignored from analysis.
The ignore glob list can be specified through the standalone config file, repo-config file, and author-config file.

Appendix: Troubleshooting

Contributions missing in the ramp chart (but appear in the contribution bar and code panel)

This is probably a case of giving an incorrect author name alias (or GitHub ID) in your author-config file.
Please refer to A Note About Git Author Name above on how to find out the correct author name you are using and how to change it.
Also, ensure that you have added all author name aliases you may be using (if you are using multiple computers or have previously changed your author name).
Alternatively, you may choose to configure RepoSense to track using your GitHub email instead of in your standalone config file or author-config file, which is more accurate compared to author name aliases. The associated GitHub email you are using can be found in your GitHub settings.

Contribution bar and code panel is empty (despite a non-empty ramp chart)

The contribution bar and code panel records the lines you have authored to the latest commit of the repository and branch you are analyzing. As such, it is possible that while you have lots of committed contributions, your final authorship contribution is low. This happens if you have only deleted lines or someone else has overwritten your code and taken authorship for it (currently, RepoSense does not have the functionality to track overwritten lines)..
It is also possible that another user has overridden the authorship of your lines using the @@author tags.

RepoSense is not using the standalone config file in my local repository

Ensure that you have committed the changes to your standalone config file first before running the analysis, as RepoSense is unable to detect uncommitted changes to your local repository.

RepoSense fails on Windows (but works on Linux/Mac OS)

Possibly, you may have some file names with special characters in them, which is disallowed in Windows OS. As such, RepoSense is unable to clone your repository fully, thus failing the analysis.

Some files are not captured by RepoSense

The files may be binary files. RepoSense does not analyze binary files. Common binary files include images (.jpg, .png), applications (.exe), zip files (.zip, .rar) and certain document types (.docx, .pptx).