Workflow¶
The three-step workflow is designed as an intuitive cognitive tool for users to navigate the literature review process.
Repeatedly calling colrev status should guide you through the different steps and operations, help you to keep track of individual papers, use different tools, and collaborate with the team.
The workflow, as illustrated in the following, consists of a three-step cycle that iterates from colrev status to a colrev [operation] to colrev validate and back to colrev status:
Although the validation step is generally recommended, it is more important for some operations than for others.
For operations like init, or operations that do not create new versions (such as push or show), the validation can be skipped.
The use of CoLRev operations ensures that the data is always formated consistently and that diffs are readable. It is also possible to create versions through git commands, which automatically trigger CoLRev’s pre-commit hooks.
CoLRev status¶
The colrev status command serves as a starting point for all steps and helps to make CoLRev self-explanatory.
It consists of the following (as shown below):
Status
Metadata retrieval 7040 processed [6198 curated]
Metadata prescreen 814 included [6226 prescreen excluded]
PDF retrieval 814 prepared
PDF screen 49 included [716 excluded]
Data synthesis 49 synthesized
Next operation
colrev dedupe
For more details: colrev status -v
The status section, which provides an overview of the review project and reports the state of the records in the process
The next operation section, which provides situational instructions on the next steps of the review project (highlighted in yellow), versioning and collaboration, and the local CoLRev environment
In the background, colrev status also checks consistency of file formats and structure.
Like all other operations, it also offers the possibility to display more detailed information (simply add -v).
CoLRev operation¶
The methodological steps of the literature review are completed through the CoLRev operations (as illustrated earlier). Once completed, operations can create new commits (versions). Detailed information on the steps and operations are provided on the following pages.
CoLRev validate¶
After each step, you can check and validate the changes using:
colrev validate .
This operation displays the most substantial changes for the selected commit and allows users to undo selected changes efficiently.
The following figure illustrates the validation for a prep operation:
validate is a general operation that allows users to validate changes in different types of commits (prep, dedupe, …),
but also changes of particular users, properties of the review or other (see cli-reference/validate <cli reference>).
For some operations (such as prep and dedupe), CoLRev provides custom validation functionality, which displays the most substantial changes first.
In other cases, CoLRev opens gitk, which displays all committed changes.
If necessary, whole versions can be undone through git clients (for an overview of git GUI clients, see here).
It is also possible to validate previous versions.
This could be done to validate the changes introduced by algorithms and teammates, and it facilitates validation of any CoLRev project by external authors.
To validate commits going back in history, run:
colrev validate HEAD
colrev validate HEAD~1
colrev validate HEAD~2
colrev validate HEAD~3
...