# mpyrpdiff

This tool generates a diff report (based on git diff) for new, modified, and
unchanged (original) files for the active branch of a repository. Optionally, a
report can be written as a markdown file.

`mpyrpdiff` compares the active branch against the common ancestor
(`merge-base`) with the branch given via `--compare-against`. It is possible
to specify a local branch, a branch available at 'origin' or a commit SHA.
From the comparison of the two branches only changes on the active branch are
reported. Changes that exist only on the branch passed via `--compare-against`
are ignored.

The index of the active branch is used for comparison with the branch given via
`--compare-against`. Changes that only affect trailing whitespace at the end of
lines are ignored. In addition, files with only a very small number of changed
lines are treated as copied instead of modified. Note that git counts a changed
line twice, one count for addition and one count for removal.

The tool takes either a list of files to be checked in detail or, if no files
are given, takes all files present in the index of the active branch.

## Usage

```bash
mpyrpdiff [options]
```

## Examples

### Basic Branch Comparison

Compare the active branch with `my-branch` and generate a short summary

```bash
mpyrpdiff --compare-against my-branch
```

For more details, e.g., a complete list of files use `--loglevel INFO`.

### Generate a Report on New, Modified and Copied Files

A markdown file with the lists for modified, copied or new files will be written
to `FILES.md`:

```bash
mpyrpdiff --compare-against my-branch --report FILES.md
```

### Limit Report to Modified Files

It is possible to limit the reporting of the tool to a specific file status,
e.g., modified files

```bash
mpyrpdiff --compare-against my-branch --modified --no-new --no-copied
```

Note, as default all file status are printed, the unwanted has to be explicitly
disabled.

### Compare Two Repositories

It is possible to use the tool for comparing two repositories, e.g., a forked
repository with respect to the original repository.  For this, the main branch
of the upstream repository has to be added to the current repository as a branch
(recommended name: 'upstream-main').

This can be done with

```shell
git remote add upstream <url-of-upstream-repo>
```

followed by

```shell
git fetch upstream && git checkout -b upstream-main upstream/main
```

Now, checkout our downstream branch again, e.g., 'main'

```shell
git checkout main
```

After this, use `--compare-against upstream-main` to compare your current
branch against the common ancestor with `upstream-main`:

```shell
mpyrpdiff --compare-against upstream-main --projectname MyFork --report FILES.md
```

This will produce a `FILES.md` like the following:

```markdown
# Files in MyFork

## New Files

- src/new_solver/newSolver.C
- src/new_solver/newSolver.H
- applications/utilities/customTool/customTool.C

## Modified Files

- src/finiteVolume/interpolation/interpolation.C
- applications/solvers/multiphase/solver.C

## Copied Files

- src/mesh/meshTools/meshTools.C
- wmake/rules/General/general
```