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 or the Global file browser will appear in place of the Code panel.

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 view details about the list of commits represented in the ramp.
  • At the commit-level of granularity, it links to the commit in the remote repository.
  • At higher levels of granularity, it displays the list of commits in the Code Panel.
• 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.

• Filter Files function allows users to refine and focus their view on specific files across all repositories by applying keyword-based filters using glob patterns. This feature is particularly beneficial for developers seeking to analyze code changes in files that match certain naming conventions or extensions.

  • Glob Pattern Filtering: Users can specify patterns to match filenames. For example:

    • **/TaskList.java: Targets all files named TaskList.java in any directory or subdirectory.
    • **/*.js: Selects all JavaScript files across all directories.
    • src/**/*.py: Finds all Python files within the src directory and its subdirectories.

  • Glob patterns use wildcards to match filenames:

    • *: Matches any sequence of characters within a single directory level.
    • **: Matches any sequence of characters across multiple directory levels.
    • ?: Matches any single character.
    • [abc]: Matches any single character within the brackets.
    • [!abc]: Matches any single character not within the brackets. These patterns provide flexibility in locating files based on specific naming conventions or extensions.
• 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.
  • Starting a search with tag: will filter author and repository by Git tags. Similar search rules as above (like separating multiple tag names by space) apply.
• 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.
  • Default: groups will be sorted by the order of rows in repo-config.csv.
• Sort within groups by: sorting criteria within each group.
  • Title: each group will be internally sorted by its 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.
• Show tags: shows the tags of all the repos under a group
• Trim timeline: trims the starting and ending portion of each ramp where no commits were made; only the part of each ramp where commits were made will be shown.

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 the remote repository.
• Clicking the second icon beside the file title opens the blame view of the file on the remote repository.
• When using the code panel for a specific author, code attributed to the author is highlighted in green.
  • When using the merge group option with group by repos, the code panel will consist of multiple authors' contributions. Code attributed to these authors can be differentiated by the highlight colors of the code. The color legend is shown at the top of each file and consists only those authors that edited a particular file.
• Non-trivial code segments that the selected author has not written 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.

Global file browser panel

The Global file browser provides a way to search and browse files across all repositories in the report. Unlike the Code panel, which shows code attributed to a single author within one repository, the global file browser lets you explore files from every repository at once.

Accessing the global file browser

1. Locate the filter mode dropdown at the top of the tool bar.
2. Select Global from the dropdown.
3. The global file browser will appear on the right side of the report, replacing the Code panel.

To return to the normal view, select Local from the dropdown. You can also click any author's or icon in the Chart panel, which automatically switches the filter mode back to Local and opens the corresponding Code or Commits panel.

Filtering files with glob patterns

The search input at the top of the panel filters files using glob patterns. The file count updates in real-time as you type.

View modes

The global file browser offers two view modes, toggled by the buttons below the search input:

Sort By Path (default)

Files from all repositories are displayed in a single flat list, sorted alphabetically by file path.

Group By Repo

Files are organized under collapsible repository headers, sorted alphabetically by repository name.

Each repository group shows:

• The repository name and total file count in the group header.
• A badge that reads Click to expand or Click to collapse, indicating the current state.
• A preview of the top 3 matching files when the group is collapsed.
• An "and N more file(s)..." link if the repository has more than 3 matching files. Clicking this link lists all remaining files (without expanding their contents).

Expanding all files in a repository group: Click the repository group header to expand (or collapse) all files in that group at once. This opens every file's content simultaneously, which is useful for quickly scanning an entire repository. Each repository group can be expanded and collapsed independently.

Viewing file contents

Click on any non-binary, non-ignored file header to expand it and view its contents. Click the same header again to collapse it.

The file content is displayed as author-colored segments:

• Each contiguous block of lines written by the same author is shown as a segment with a colored left border identifying the author.
• Hover over a segment to see a tooltip showing the author's name and whether they are the primary author or a co-author.

Use cases

The global file browser is particularly useful for:

• Cross-repository code search: Find files matching a specific pattern (e.g., *.yml for CI configs) across all repositories.
• Code review: Quickly browse all files of a specific type and see who wrote each line.
• Comparing implementations: Filter for files with similar names or extensions across different repositories to compare how they are implemented.
• Identifying authorship: Expand files to see author-colored segments, making it easy to identify who contributed which parts of a file.