Appendix: Config files format

config.json (standalone config file)

Repo owners can provide the following additional information to RepoSense using a config file that we call the standalone config file:

• which files/authors/commits to analyze/omit
• which Git and Git host usernames belong to which authors
• the display of an author

To use this feature, add a _reposense/config.json to the root of your repo using the format in the example below (another example) and commit it (reason: RepoSense can see committed code only):

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

Note: all fields are optional unless specified otherwise.

Fields to provide repository-level info:

• ignoreGlobList: Folders/files to ignore, specified using the glob format.
• formats: File formats to analyze. Binary file formats, such as png and jpg, will be automatically labelled as the file type binary in the generated report. Default: all file formats
• ignoreCommitList: The list of commits to ignore during analysis. For accurate results, the commits should be provided with their full hash. Additionally, a range of commits can be specified using the .. notation e.g. abc123..def456 (both inclusive).
• ignoreAuthorList: The list of authors to ignore during analysis. Authors specified in authors field or author-config.csv will be also be omitted if they are in this list. Authors should be specified by their Git Author Name.
• fileSizeLimit: A file size limit for the repository in bytes as a single number without units, that will override the default file size limit. If not specified, the default file size limit will continue to be used.

Fields to provide author-level info:
Note: authors field should contain all authors that should be captured in the analysis.

• gitId: Username of the author. mandatory field.
• emails: Associated Git emails of the author. For GitHub, this can be found in your GitHub settings.
• displayName: Name to display on the report for this author.
• authorNames: Git Author Name(s) used in the author's commits. By default, RepoSense assumes an author would use their remote Git Host username as the Git username too. The meaning of Git Author Name is explained in A note about Git author name.
• ignoreGlobList: Additional (i.e. on top of the repo-level ignoreGlobList) folders/files to ignore for a specific author. The path glob syntax is specified by the glob format. In the example above, the actual ignoreGlobList for alice would be ["about-us/**", "**index.html", "**.css"].

To verify your standalone configuration is as intended, add the _reposense/config.json to your local copy of repo and run RepoSense against it as follows:

• Format: java -jar RepoSense.jar --repo LOCAL_REPO_LOCATION
  
• Example: java -jar RepoSense.jar --repo c:/myRepose/foo/bar
  After that, view the report to see if the configuration you specified in the config file is being reflected correctly in the report.

A note about Git author name

Git Author Name refers to the customizable author's display name set in the local .gitconfig file. For example, in the Git Log's display:

...
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: ActualGitHostId <author@example.com>
Date:   Fri Feb 9 19:13:13 2018 +0800

    Initial commit
 ...

ActualGitHostId and ConfiguredAuthorName are both Git Author Name of the same author.
To find the author name that you are currently using for your current Git repository, run the following command within your Git repository:

git config user.name

To set the author name to the value you want (e.g., to set it to your GitHub username) for your current Git repository, you can use the following command (more info):

git config user.name "YOUR_AUTHOR_NAME”

To set the author name to use a default value you want for future Git repositories, you can use the following command:

git config --global user.name "YOUR_AUTHOR_NAME”

RepoSense expects the Git Author Name to be the same as author's username on the Git hosting platform (GitHub, GitLab, BitBucket). If an author's Git Author Name is different from their username on the Git hosting platform, the Git Author Name needs to be specified in the standalone config file. If the author has more than one Git Author Name, multiple values can be entered too.

blurbs.md

You can optionally use blurbs.md to add blurbs in Markdown syntax for repository branches. These blurbs will be seen when grouping by Repo/Branch. (example)

Format:

• First line in section: Link to the repository branch.
• Second line onwards: Blurb content.
• Delimiter: <!--repo-->. Everything on the line after the delimiter will be ignored.