How to try out any JabRef pull request

JabRef gets many contributions by external contributors in the form of pull requests. Want to try out the feature or fix? You can now do so in a few simple steps, and give early feedback!

For instance, to try out the “initial implementation of walkthrough”, one needs to execute following command:

• Windows: .\gg.cmd just run-pr 13182
• macOS/Linux: sh ./gg.cmd just run-pr 13182

Preparation

To make this work, one needs to have gg.cmd available in JabRef’s source directory.

This can be achieved by using gg.cmd, JBang, and scripts offered by JabRef:

1. Download gg.cmd
2. Instruct JBang to trust JabRef: Execute .\gg.cmd jbang trust add https://github.com/JabRef/jabref/.
   
   
3. Clone JabRef into a folder. By default, a system-wide available temporary folder is used. (In “Advanced Hints” below, we mention steps on how to use a specific folder.) Execute .\gg.cmd jbang https://github.com/JabRef/jabref/blob/main/.jbang/CloneJabRef.java.
   

4. After it finishes, it will output the directory:

   JabRef code available at: C:\Users\WDAGUtilityAccount\AppData\Local\Temp\jabref
   

5. Go to the directory: cd C:\Users\WDAGUtilityAccount\AppData\Local\Temp\jabref (Note - replace “WDAGUtilityAccount” with your username).
6. Move gg.cmd to here: move C:\Users\WDAGUtilityAccount\Downloads\gg.cmd .. (Note - replace “WDAGUtilityAccount” with your username. The path also needs to be changed if you have downloaded gg.cmd anywhere else.)
7. Now you can run a PR using .\gg.cmd just run-pr 13182 (replace 13182 with the PR number of whichever PR you want to try out). Initially, this might take several minutes, as the build environment has to be initialized and JabRef is built completely from scratch. In subsequent runs, the process is much faster.

Advanced Hints

Using another directory

In step 3, a temporary folder was used. You can also use a different directory. For example, following command clones into a directory jabref located in the current folder:

.\gg.cmd jbang https://github.com/JabRef/jabref/blob/main/.jbang/CloneJabRef.java jabref

In general, any (non-existing) directory can be used. To clone into c:\git-repositories\jabref, use following command:

.\gg.cmd jbang https://github.com/JabRef/jabref/blob/main/.jbang/CloneJabRef.java c:\git-repositories\jabref

Linux and macOS

For Linux and macOS, use sh ./gg.cmd instead of .\gg.cmd.

Running JabKit

You can run other parts of JabRef. For instance for JabKit:

.\gg.cmd just run-jabkit --help

Using a Windows Sandbox

Windows Sandbox is a nice feature to run a clean Windows system and have it deleted after use.

There is CustomSandbox with a nice Terminal-based UI to configure the Sandbox. We modified it to include gg.cmd. To use, follow these steps:

1. Download https://github.com/koppor/CustomSandbox/archive/refs/heads/main.zip
2. Extract it.
3. Start “PowerShell”.
4. cd into the directory where you extraced it.
5. Start the script: .\CustomSandbox.ps1.
6. In the first screen, enable [x] Networking and [x] Save Configuration.
7. In the second screen, enable [x] [Chocolatey] Microsoft VC++ Redist for VS 2015-2022, because this is required for JabRef’s AI functionality. It will also enable some other packages required for installation.
8. Also enable [x] Download gg.cmd.
9. After pressing Enter, dependencies will be downloaded.
10. Afterwards, one has to press Enter again to launch the sandbox.
11. There, the chosen dependencies will be installed.
12. Now, you can start PowerShell and continue with step 2 from above to instruct JBang to trust JabRef’s code.

As usual, the first run takes a long time, because it will download all required files. The second run will be faster, because the files are cached.

Special Thanks

• gg.cmd for automatic downloading and execution of required tooling.
• JBang for enabling easy execution of .java files.
• Eclipse JGit for making git available as pure Java library.

More Information

More information is available in our contributing guide.