Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fix some minor cosmetic issues in docs #2218

Closed
wants to merge 5 commits into from
Closed

Fix some minor cosmetic issues in docs #2218

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
e6dfa3d
variables.md: Use <varialbe> syntax
May 16, 2024
43e97c8
docs: Remove variables.json
May 16, 2024
2c39b14
Update outdated links to example reports
May 16, 2024
8d75802
Fix typo: git -> Git
May 16, 2024
b1fa8ac
Merge branch 'master' into doc-tweaks
ckcherry23 May 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 0 additions & 3 deletions docs/_markbind/variables.json
View file
Open in desktop

This file was deleted.

82 changes: 40 additions & 42 deletions docs/_markbind/variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,42 +1,40 @@
<span id="icon_announcement"><md>:fas-bell:</md></span>
<span id="icon_book"><md>:fas-book:</md></span>
<span id="icon_calendar"><md>:fas-calendar-alt:</md></span>
<span id="icon_dislike"><md>:fas-thumbs-down:</md></span>
<span id="icon_example"><md>:fas-cube:</md></span>
<span id="icon_embedding"><md>:glyphicon-log-in:</md></span>
<span id="icon_exercise"><md>:fas-dumbbell:</md></span>
<span id="icon_extra"><span class='badge rounded-pill bg-secondary'><md>:fas-plus: extra</md></span></span>
<span id="icon_info"><md>:fas-info-circle:</md></span>
<span id="icon_like"><md>:fas-thumbs-up:</md></span>
<span id="icon_linux"><md>:fab-linux:</md></span>
<span id="icon_level_basic"><md><span class="badge rounded-pill bg-danger">:far-star:</span></md></span>
<span id="icon_level_intermediate"><md><span class="badge rounded-pill bg-warning text-white">:far-star::far-star:</span></md></span>
<span id="icon_level_advanced"><md><span class="badge rounded-pill bg-success">:far-star::far-star::far-star:</span></md></span>
<span id="icon_important_big_red"><font color="red"><big>:glyphicon-exclamation-sign:</big></font></span>
<span id="icon_important"><md>:glyphicon-exclamation-sign:</md></span>
<span id="icon_new_window"><md>:glyphicon-new-window:</md></span>
<span id="icon_outcome"><md>:fas-trophy:</md></span>
<span id="icon_output"><md>:fas-arrow-down:</md></span>
<span id="icon_output_right"><md>:fas-arrow-right:</md></span>
<span id="icon_print"><md>:glyphicon-print:</md></span>
<span id="icon_prereq"><md>:glyphicon-education:</md></span>
<span id="icon_preview"><md>:glyphicon-eye-open:</md></span>
<span id="icon_pro_tip"><span class="badge rounded-pill bg-warning">:fas-lightbulb: PRO TIP</span></span>
<span id="icon_Q"><md>:glyphicon-question-sign:</md></span>
<span id="icon_Q_A">{{ icon_Q | safe }}:glyphicon-ok-sign:</span>
<span id="icon_resource"><md>:fas-paperclip:</md></span>
<span id="icon_terminal"><smal><span class="badge bg-secondary">&gt;_</span></smal></span>
<span id="icon_text"><md>:far-file-alt:</md></span>
<span id="icon_tick"><md>:fas-check:</md></span>
<span id="icon_tip"><span class="badge rounded-pill bg-warning">:fas-lightbulb:</span></span>
<span id="icon_tick_green"><span style="color:green">{{ icon_tick | safe }}</span></span>
<span id="icon_todo"><md>:glyphicon-check:</md></span>
<span id="icon_slides"><md>:far-images:</md></span>
<span id="icon_video"><md>:glyphicon-facetime-video:</md></span>
<span id="icon_windows"><md>:fab-windows:</md></span>
<span id="icon_x"><md>:fas-times:</md></span>
<span id="icon_x_red"><span style="color:red">{{ icon_x | safe }}</span></span>
<span id="bad"><font color="red"><md>**{{ icon_dislike | safe }} Bad**</md></font></span>
<span id="good"><font color="green"><md>**{{ icon_like | safe }} Good**</md></font></span>

<variable from="variables.json" />
<variable name="icon_announcement"><md>:fas-bell:</md></variable>
<variable name="icon_book"><md>:fas-book:</md></variable>
<variable name="icon_calendar"><md>:fas-calendar-alt:</md></variable>
<variable name="icon_dislike"><md>:fas-thumbs-down:</md></variable>
<variable name="icon_example"><md>:fas-cube:</md></variable>
<variable name="icon_embedding"><md>:glyphicon-log-in:</md></variable>
<variable name="icon_exercise"><md>:fas-dumbbell:</md></variable>
<variable name="icon_extra"><span class='badge rounded-pill bg-secondary'><md>:fas-plus: extra</md></span></variable>
<variable name="icon_info"><md>:fas-info-circle:</md></variable>
<variable name="icon_like"><md>:fas-thumbs-up:</md></variable>
<variable name="icon_linux"><md>:fab-linux:</md></variable>
<variable name="icon_level_basic"><md><span class="badge rounded-pill bg-danger">:far-star:</span></md></variable>
<variable name="icon_level_intermediate"><md><span class="badge rounded-pill bg-wg text-white">:far-star::far-star:</span></md></variable>
<variable name="icon_level_advanced"><md><span class="badge rounded-pill bg-success">:far-star::far-star::far-star:</span></md></variable>
<variable name="icon_important_big_red"><font color="red"><big>:glyphicon-exclamation-sign:</big></font></variable>
<variable name="icon_important"><md>:glyphicon-exclamation-sign:</md></variable>
<variable name="icon_new_window"><md>:glyphicon-new-window:</md></variable>
<variable name="icon_outcome"><md>:fas-trophy:</md></variable>
<variable name="icon_output"><md>:fas-arrow-down:</md></variable>
<variable name="icon_output_right"><md>:fas-arrow-right:</md></variable>
<variable name="icon_print"><md>:glyphicon-print:</md></variable>
<variable name="icon_prereq"><md>:glyphicon-education:</md></variable>
<variable name="icon_preview"><md>:glyphicon-eye-open:</md></variable>
<variable name="icon_pro_tip"><span class="badge rounded-pill bg-warning">:fas-lightbulb: PRO TIP</span></variable>
<variable name="icon_Q"><md>:glyphicon-question-sign:</md></variable>
<variable name="icon_Q_A">{{ icon_Q | safe }}:glyphicon-ok-sign:</variable>
<variable name="icon_resource"><md>:fas-paperclip:</md></variable>
<variable name="icon_terminal"><smal><span class="badge bg-secondary">&gt;_</span></smal></variable>
<variable name="icon_text"><md>:far-file-alt:</md></variable>
<variable name="icon_tick"><md>:fas-check:</md></variable>
<variable name="icon_tip"><span class="badge rounded-pill bg-warning">:fas-lightbulb:</span></variable>
<variable name="icon_tick_green"><span style="color:green">{{ icon_tick | safe }}</span></variable>
<variable name="icon_todo"><md>:glyphicon-check:</md></variable>
<variable name="icon_slides"><md>:far-images:</md></variable>
<variable name="icon_video"><md>:glyphicon-facetime-video:</md></variable>
<variable name="icon_windows"><md>:fab-windows:</md></variable>
<variable name="icon_x"><md>:fas-times:</md></variable>
<variable name="icon_x_red"><span style="color:red">{{ icon_x | safe }}</span></variable>
<variable name="bad"><font color="red"><md>**{{ icon_dislike | safe }} Bad**</md></font></variable>
<variable name="good"><font color="green"><md>**{{ icon_like | safe }} Good**</md></font></variable>
2 changes: 1 addition & 1 deletion docs/dg/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@
* [`GitShortlog`](https://github.com/reposense/RepoSense/blob/master/src/main/java/reposense/git/GitShortlog.java): Wrapper class for `git shortlog` functionality. Obtains the list of authors who have contributed to the target repo.
* [`GitShow`](https://github.com/reposense/RepoSense/blob/master/src/main/java/reposense/git/GitShow.java): Wrapper class for `git show` functionality. Gets the date of the commit with the commit hash.
* [`GitUtil`](https://github.com/reposense/RepoSense/blob/master/src/main/java/reposense/git/GitUtil.java): Contains helper functions used by the other Git classes above.
* [`GitVersion`](https://github.com/reposense/RepoSense/blob/master/src/main/java/reposense/git/GitVersion.java): Wrapper class for `git --version` functionality. Obtains the current git version of the environment that RepoSense is being run on.
* [`GitVersion`](https://github.com/reposense/RepoSense/blob/master/src/main/java/reposense/git/GitVersion.java): Wrapper class for `git --version` functionality. Obtains the current Git version of the environment that RepoSense is being run on.

<box type="info" seamless>

Expand Down
2 changes: 1 addition & 1 deletion docs/dg/report.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ The tabbed interface is responsible for loading various modules such as authorsh

- **summary.json** - a list of all the repositories and their respective details
- **projName/commits.json** - contains information of the users' commits information (e.g., line deletion, insertion, etc.), grouped by date
- **projName/authorship.json** - contains information from git blame, detailing the author of each line for all the processed files
- **projName/authorship.json** - contains information from `git blame`, detailing the author of each line for all the processed files

<!-- ==================================================================================================== -->

Expand Down
2 changes: 1 addition & 1 deletion docs/dg/settingUp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
**Prerequisites:**
* **JDK `11.0.21+9`** up to **`17`** ([download :fas-download:](https://www.oracle.com/technetwork/java/javase/downloads/index.html)).
* **Node.js** **`18`** up to the latest minor version of **`19`** ([download :fas-download:](https://www.npmjs.com/get-npm)).
* **git `2.23`** or later ([download :fas-download:](https://git-scm.com/downloads)).
* **Git `2.23`** or later ([download :fas-download:](https://git-scm.com/downloads)).

<box type="info" seamless>

Expand Down
2 changes: 1 addition & 1 deletion docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
<h1 class="display-3">RepoSense</h1>
<div class="lead">

Visualize programmer activities across git repositories...
Visualize programmer activities across Git repositories...
<br><br>
<img src="images/reposenseOverview.png" width="909" alt="RepoSense overview"/>
<br><br>
Expand Down
2 changes: 1 addition & 1 deletion docs/ug/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -215,7 +215,7 @@ credit is given.
### `--repo`, `--repos`, `-r`

**`--repo REPO_LOCATION`**: Specifies which repositories to analyze.
* Parameter: `REPO_LOCATION` A list of URLs or the disk location of the git repositories to analyze, separated by spaces.
* Parameter: `REPO_LOCATION` A list of URLs or the disk location of the Git repositories to analyze, separated by spaces.
* Alias: `-r`
* Examples:
* `--repos https://github.com/reposense/RepoSense.git`
Expand Down
18 changes: 9 additions & 9 deletions docs/ug/configFiles.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Given below are the details of the various config files used by RepoSense.

| Column Name | Explanation |
|-------------|-------------|
| Repository's Location {{ mandatory }} | The `Remote Repo URL` or `Disk Path` to the git repository e.g., `https://github.com/foo/bar.git` or `C:\Users\user\Desktop\GitHub\foo\bar` |
| Repository's Location {{ mandatory }} | The `Remote Repo URL` or `Disk Path` to the Git repository e.g., `https://github.com/foo/bar.git` or `C:\Users\user\Desktop\GitHub\foo\bar` |
| Branch | The branch to analyze in the target repository e.g., `master`. Default: the default branch of the repo |
| File formats<sup>*+</sup> | The file extensions 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 |
| Find Previous Authors | Enter **`yes`** to utilize Git blame's ignore revisions functionality, RepoSense will attempt to blame the line changes caused by commits in the ignore commit list to the previous authors who altered those lines (if available). |
Expand Down Expand Up @@ -75,7 +75,7 @@ Optionally, you can use an `author-config.csv` (which should be in the same dire
| Author's Git Host ID<sup>#</sup> {{ mandatory }} | Username of the target author's profile on GitHub, GitLab or Bitbucket, e.g.`JohnDoe`. |
| Author's Emails<sup>*</sup> | Associated emails of the author. For GitHub users, this can be found in your [GitHub settings](https://github.com/settings/emails). |
| Author's Display Name | The name to display for the author. Default: author's username. |
| Author's Git Author Name<sup>*</sup> | The meaning of _Git Author Name_ is explained in [_A note about git author name_](#a-note-about-git-author-name). |
| Author's Git Author Name<sup>*</sup> | The meaning of _Git Author Name_ is explained in [_A note about Git author name_](#a-note-about-git-author-name). |
| Ignore Glob List<sup>*</sup> | Files to ignore for this author, in addition to files ignored by the patterns specified in `repo-config.csv`. The path glob syntax is the same as that of Ignore Glob List in `repo-config.csv`. |

<sup>* **Multi-value column**: multiple values can be entered in this column using a semicolon `;` as the separator.</sup>
Expand Down Expand Up @@ -122,7 +122,7 @@ You can optionally use `report-config.json` to customize report generation by pr

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
* 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](https://github.com/reposense/RepoSense/blob/master/_reposense/config.json)) and **commit it** (reason: RepoSense can see committed code only):
Expand Down Expand Up @@ -160,17 +160,17 @@ Note: all fields are optional unless specified otherwise.
**Fields to provide _author-level_ info**:<br>
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](https://github.com/settings/emails).
* `emails`: Associated Git emails of the author. For GitHub, this can be found in your [GitHub settings](https://github.com/settings/emails).
* `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_](#a-note-about-git-author-name).
* `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_](#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_](https://docs.oracle.com/javase/tutorial/essential/io/fileOps.html#glob). 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:<br>
* Format: `java -jar RepoSense.jar --repo LOCAL_REPO_LOCATION` <br>
* Example: `java -jar RepoSense.jar --repo c:/myRepose/foo/bar`<br>
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
## 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:
``` {.no-line-numbers}
Expand All @@ -189,15 +189,15 @@ Date: Fri Feb 9 19:13:13 2018 +0800
...
```
`ActualGitHostId` and `ConfiguredAuthorName` are both `Git Author Name` of the same author.<br>
To find the author name that you are currently using for your current git repository, run the following command within your git repository:
To find the author name that you are currently using for your current Git repository, run the following command within your Git repository:
``` shell {.no-line-numbers}
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](https://www.git-tower.com/learn/git/faq/change-author-name-email)):
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](https://www.git-tower.com/learn/git/faq/change-author-name-email)):
``` shell {.no-line-numbers}
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:
To set the author name to use a default value you want for future Git repositories, you can use the following command:
``` shell {.no-line-numbers}
git config --global user.name "YOUR_AUTHOR_NAME”
```
Expand Down
4 changes: 2 additions & 2 deletions docs/ug/customizingReports.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ The report can be customized using several ways, as explained below.

<box type="tip" seamless>

**Managing config files collaboratively**: If you use RepoSense to monitor a large number of programmers, it may be more practical to get the programmers to submit PRs to update the config files as necessary (<tooltip content="a coder realizes some of her code is missing from the report because she used multiple git usernames, and wants to add the additional usernames to the config file">example use case</tooltip>).
**Managing config files collaboratively**: If you use RepoSense to monitor a large number of programmers, it may be more practical to get the programmers to submit PRs to update the config files as necessary (<tooltip content="a coder realizes some of her code is missing from the report because she used multiple Git usernames, and wants to add the additional usernames to the config file">example use case</tooltip>).

To ensure that their PRs are correct, you can use [Netlify _deploy previews_](https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/) to preview how the report would look like after the PR has been merged. More details are in the panels below.

Expand All @@ -58,7 +58,7 @@ In both instances, it is **necessary to commit any changes** for them to be dete

</box>

3\. Add a git `.mailmap` file at the top-level of the repository, specifying mapped authors/commiters and/or e-mail addresses as per [gitmailmap documentation](https://git-scm.com/docs/gitmailmap). Any mappings specified here will be applied by git before all other RepoSense configurations. Configuration via `.mailmap` is particularly useful if you want the mapping to apply for all git commands as well instead of just for RepoSense.
3\. Add a Git `.mailmap` file at the top-level of the repository, specifying mapped authors/commiters and/or e-mail addresses as per [gitmailmap documentation](https://git-scm.com/docs/gitmailmap). Any mappings specified here will be applied by Git before all other RepoSense configurations. Configuration via `.mailmap` is particularly useful if you want the mapping to apply for all Git commands as well instead of just for RepoSense.

<!-- ------------------------------------------------------------------------------------------------------ -->

Expand Down
4 changes: 2 additions & 2 deletions docs/ug/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@
<!-- ------------------------------------------------------------------------------------------------------ -->

### 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.<br>
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.
**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.<br>
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.

<!-- ------------------------------------------------------------------------------------------------------ -->

Expand Down
Loading
Loading