gitpseudo

Command line tool to pseudonymize git repositories using git-filter-repo

This small library provides a command line tool in order to replace author names and emails from git logs with pseudonyms.

Install

This tool requires https://github.com/newren/git-filter-repo to be installed. Please follow the instructions there.

Install with npm:

npm install --save-dev gitpseudo

or simply run with npx:

npx gitpseudo [options]

Usage

If you start the tool in the project:

npm run build
node dist/cli.js

With npx:

Usage: gitpseudo [options] [command]

The tool has the following commands:

Prepare

The prepare commands can unzip a bunch of zip files, rename folders using regular expressions and clean repository folders.

The idea behind the prepare command is to pre-process the folders, often provided by a tool such as Moodle. That is, the Git-Repositories might stem from assignments, and you want to remove all names from the repositories and the folders.

The default configuration is set for Moodle, but you can easily change it to your needs. That is, if a submission is provided using Moodle, it is usually contained in a zip file you can download from Moodle. This zip contains a folder for each student with the name of the student.

Example: For an assignment "Task X" of a course "Course", the lecturer can download a file Course-Task X-123456.zip. In this zip you will find the following structure:

John Doe_4567892_assignsubmission_file_
  + submitted files
Jane Doe 8548854_assignsubmission_file_
  + submitted files
...

The submitted files may contain a zip file with a git repository. That is, you want to perform the following steps:

1. Unzip all zip files (including zip files inside zip files)
2. Rename all folders with a student name (using a regular expression)
3. Maybe clean the repository (remove all files except for the ones in the .git folder)

Note that you might want to use https://www.npmjs.com/package/ziplocalgit so that students can easily create a zip file of their local git.

For that, you an use the prepare command. The default settings match the example above. For that, you would call

gitpseudo prepare --unzip --rename --clean -d "/some/path/to/folder" -r

For more information on the command, run gitpseudo prepare --help

Rewrite

The rewrite commands uses https://github.com/newren/git-filter-repo to rewrite the git history, pseudonymizizing all names and email addresses.

In short, all names are replaced with a prefix string ('author' by default) and a serial number. All emails are replaced with the same prefix string, if a name has multiple email addresses, another serial number is used.

Unfortunately, the git-filter-repo tool always resets the git repository, i.e. if you have an empty git folder, it is populated with the latest revision. So, if you want to copy the repo later on (this is usually why you do the pseudonymization in the first place), you probably want to use the --clean option.

Example:

gitpseudo rewrite -d "/some/path/to/folder" -r --clean -w [email protected]

If not otherwise specified, the tool will create a file mailmap.txt which is used for rewriting and which can also be used later on to get the real names from the pseudo names. Do not copy that file along with the pseudonymized repository!

For more information on the command, run gitpseudo rewrite --help

Status

This library is developed on demand. It only contains features as far as needed by the author. It is basically made public in order to simplify the author's scripts. This tool is an extended TypeScript version of a script found at https://github.com/qqdp/git-pseudonymizer/blob/main/git-pseudonymizer.sh

License

This program and the accompanying materials are made available under the terms of the Eclipse Public License v. 2.0 which is available at https://www.eclipse.org/legal/epl-2.0.