Git Administration

Documentation / Administrate

Table of Contents

You can collaborate on ReqView projects managed in Git as described in Collaborate via Git. To enable this type of collaboration, install Git on your computer, set up a Git repository and import your ReqView project to the repository.

Install Git

First, install Git command line tools for your platform as described in Install Git Client.

Set up Git Repositories

You can host Git repositories at your premises (self-managed) or in cloud (SaaS), depending on Git provider. GitHub, GitLab, Atlassian BitBucket and Microsoft Azure DevOps offer both options. If you prefer managing a plain Git server completely yourselves, see Pro Git: Git on the Server.

Once you have set up your account at a Git provider, follow the steps below to import a ReqView Project Folder into a new Git repository.

  1. Create a new empty remote repository using the web interface of your Git provider:

    Some Git providers offer command line tools to help you automate creation of many repositories.

  2. Initialize a new local Git repository in an empty folder and create the default branch main:

    $ mkdir <reqview_project_folder>
    $ git init --initial-branch=main

    Note: You can also name the default branch master if needed.

  3. Optionally, configure Git Large File Storage (LFS) extension to optimize performance of Git operations if your ReqView project includes large binary attachments (diagrams, MS Word or Excel documents, PDF files, etc.). See Configure Git LFS for more information.

  4. Save a ReqView project into <reqview_project_folder>, see Requirements Projects > Save Projects. Or, just copy an existing ReqView Project Folder into <reqview_project_folder> from the command line:

    $ cp -R <existing_reqview_project_folder> <reqview_project_folder>

  5. Add all ReqView project files to the local Git repository:

    $ cd <reqview_project_folder>
    $ git add .
    $ git commit -m "Initial import of ReqView project"

  6. Connect the local Git repository to the remote Git repository created in Step 1 and push changes to branch main:

    $ git remote add origin <git_repository_url>
    $ git push --set-upstream origin main

  7. To test connection to the remote Git repository, open the Project Folder in ReqView and show Git information.

Organize Git Repositories

We recommend storing each ReqView Project Folder in a separate Git repository because this layout has many advantages:

  • Organization of Git repositories is simple and uniform across all ReqView projects.
  • You can create a workspace that clones only a subset of projects locally.
  • You can set up different access rights for each project repository.
  • You can baseline each project independently.

Example: The following screenshot illustrates the layout of a Git repository that stores the Example Project in GitLab:

Git repository storing a ReqView project folder

Control User Access

ReqView projects are accessed by several groups of users. For instance, one group of users collaborates with a specific customer and needs to update stakeholder requirements. Another group develops a specific SW component and needs to read stakeholder and system requirements only and update SW requirements for the developed component.

You can store ReqView projects in separate Git repositories and control read / write access for specific users or user groups conveniently. To set up user access rights, follow instructions provided by your Git hosting provider:

Create Workspace

Most users are only interested in a subset of ReqView projects. For instance, they update stakeholder requirements for a specific customer. Or they develop a specific SW component. You can prepare a local workspace by cloning only a specific set of Git repositories for each group of users. The workspace should keep a predefined hierarchy of project folders to allow linked projects to reference each other by relative paths.

The easiest way to create a workspace with a given hierarchy of project folders is to run a script that clones the default branch of selected Git repositories.

Example: Create local workspace for a customer facing team working on ReqView project CUSTOMER1. Members of this team also need to export traceability reports displaying coverage of stakeholder requirements by system requirements from ReqView project SYSTEM1. However, they do not need to access other ReqView projects storing requirements for other systems or HW/SW subsystems. The workspace for this team contains the following structure of project folders:

/
    STAKEHOLDERS/
        CUSTOMER1/
    SYSTEMS/
        SYSTEM1/

To create the workspace, run the following script in an empty folder:

git clone <git_repository1_url> STAKEHOLDERS/CUSTOMER1
git clone <git_repository2_url> SYSTEMS/SYSTEM1

Where <git_repository1_url> is the URL of Git repository storing ReqView project CUSTOMER1, and <git_repository2_url> is the URL of Git repository storing ReqView project SYSTEM1.

The workspace will reference the default branch (main or master) configured for each cloned Git repository.

Configure Git LFS

Performance of some Git operations may drop for repositories storing large binary files that are modified regularly. To prevent this issue we recommend configuring the Git LFS extension for ReqView projects with large attachments. Git LFS extension replaces binary content of attachments in Git repositories by references to binary files stored at a remote server. This approach enables to download large files lazily during checkout instead of during cloning or fetching. See Git LFS Tutorial by Atlassian for more information. All popular Git hosting providers supports Git LFS out of the box.

Note: ReqView uses its internal locking mechanism for project and document files. To prevent unpredictable errors, do not make Git LFS files lockable by running git lfs track with the --lockable flag!

To configure Git LFS extension for an empty Git repository that will store a ReqView project with large attachments, follow these steps:

  1. Install git-lfs command line extension. On Windows, it is installed with Git command line tools automatically. To install git-lfs on other platforms:

    • Linux: Run apt-get command sudo apt-get install git-lfs on Ubuntu or Debian Linux.
    • Mac: Run Homebrew command brew install git-lfs.

  2. Enable Git LFS extension for a Git repository, see instructions provided by your Git hosting provider:

  3. Initialize Git LFS project:

    $ git lfs install

  4. Set all attachments to be tracked as large binary files. Add file .gitattributes to the Git repository. Commit changes and push them to the remote repository:

    $ git lfs track "attachments/**"
    $ git add .gitattributes
    $ git commit -am "Enable Git LFS for attachments"
    $ git push origin main

Note: To configure Git LFS extension for a Git repository that already stores a ReqView project, either run git add --renormalize . after git lfs track in Step 4 above, or use git-lfs-migrate, see Git LFS FAQs - Tracking and Migration.

Force Release of Git Locks

As an administrator, you can release project or document locks when the editor cannot release the lock from ReqView, for instance if their computer is broken or if they leave the company with a document locked for editing.

ReqView implements exclusive edit access using using Git references stored in the hidden directory .git. ReqView references have file prefix .git/refs/reqview/*.

To release a project or document lock created by other users:

  1. List all locks in the repository using git ls-remote command:

    $ git ls-remote origin "refs/reqview/locks/*"
    4a8141564ee14fb97a07facd7f2b2f9adfc171cf        refs/reqview/locks/documents/INF.json
    81ec6e41ca4b4bd12d899dec176df56f6cce4f7e        refs/reqview/locks/documents/NEEDS%201.json
    9b3fb57469baf1ec318cfe4acc29eade90b6b53a        refs/reqview/locks/documents/NEEDS%202.json

    Note: Special characters in paths are encoded using percent-encoding. For example, the lock for document NEEDS 2 is stored in Git reference refs/reqview/locks/documents/NEEDS%202.json, where the space character is encoded as %20.

  2. Delete the chosen locks using git push -d command.

    Example: Delete lock files for documents INF and NEEDS 2:

    $ git push -d origin refs/reqview/locks/documents/INF.json refs/reqview/locks/documents/NEEDS%202.json

Note: Breaking a ReqView file lock manually can lead to merge conflicts that are difficult to resolve manually. Try to avoid it whenever possible.

Migrate From SVN to Git

You can migrate an SVN repository storing ReqView projects to Git repositories using the git-svn command line tool. This tool is installed with Git command line tools automatically on Windows. To install git-svn on other platforms:

  • Linux: Run apt-get command sudo apt-get install git-svn on Ubuntu or Debian Linux.
  • Mac: Run Homebrew command brew install git-svn.

SVN repositories can store one or multiple ReqView projects flexibly. There are two typical layouts — a basic layout for simple products with a few projects and an advanced layout for complex products with many projects, see SVN Administration > Organize SVN Repositories. We recommend migrating each single ReqView project from a SVN repository to a separate Git repository for the reasons explained in Organize Git Repositories.

To migrate a single ReqView project preserving project history and baselines, follow the instructions provided by your Git hosting provider:

Optionally, you can configure the Git Large File Storage (LFS) extension to optimize performance of Git operations if the migrated project includes large binary attachments, see Configure Git LFS.

Example: Migrate the Example System Project stored in SVN repository using the advanced layout:

/
    STAKEHOLDERS/
        CUSTOMER1/
            trunk/
            tags/
        ...
    SYSTEMS/
        SYSTEM1/
            trunk/
            tags/
        ...
    ...

First, create a list of all authors from the migrated SVN repository into a text file using svn log command. For example, use awk and sort to create file authors.txt:

$ cd <svn_reqview_project>
$ svn log -q | awk -F '|' '/^r/ {sub("^ ", "", $2); sub(" $", "", $2); print $2" = "$2" <"$2">"}' | sort -u > authors.txt

Then, make sure the list of authors contains proper names and emails. For example, set esmith = Emma Smith <emma.smith@example.com>.

To migrate the ReqView project STAKEHOLDERS/CUSTOMER1, follow these steps:

  1. Run git svn clone on the SVN trunk version of a migrated ReqView project. Use --authors-file argument to pass the file with authors. Use --stdlayout argument because the repository uses the standard trunk and tags layout.

    $ git svn clone <svn_repository>/STAKEHOLDERS/CUSTOMER1 --authors-file=<svn_reqview_project>/authors.txt --no-metadata --prefix="" --stdlayout STAKEHOLDERS/CUSTOMER1

    Where <svn_repository> is the URL of the migrated SVN repository.

  2. Convert all SVN tags into Git tags.

    $ cd STAKEHOLDERS/CUSTOMER1
    $ for t in $(git for-each-ref --format='%(refname:short)' refs/remotes/tags); do git tag ${t/tags\//} $t && git branch -D -r $t; done

  3. Set up a new empty Git remote repository, see Set up Git Repositories.

  4. Push to remote Git repository.

    $ git remote add origin <git_repository>
    $ git push origin --all
    $ git push origin --tags

    Where <git_repository> is the URL of the new Git repository created in the previous step.

You can implement a simple script that repeats these steps for all ReqView projects in the migrated SVN repository.

If you migrate linked projects from SVN:

  1. Set up a hierarchy of local Git working trees that is identical to the hierarchy in the migrated SVN working copy. You can do that by a script cloning linked projects, see Create Workspace.

  2. Because SVN and Git represent branches and tags differently, you need to reconnect linked projects.

    You can do that in ReqView, see Connect Linked Projects. For example, open Git working tree with project STAKEHOLDERS/CUSTOMER1 in ReqView and connect it to Git working tree with project SYSTEMS/SYSTEM1.

    You can also reconnect multiple linked projects at once using search & replace in a text editor. For example, modify the project file STAKEHOLDERS/CUSTOMER1/project.json as follows:

        "linkedProjects": [
            {
    -         "path": "../../SYSTEMS/SYSTEM1/trunk",
    +         "path": "../../SYSTEMS/SYSTEM1",
              "projectId": "SYSTEM1"
            }
        ]

    See also Open File Data Format for JSON schema of project files.

Updated for version 2.19.0