GSoC 2017: Git Support (final report)

Intro

Google Summer of Code (GSoC) is an international annual program held by Google, in which Google provides a platform for open source organizations to recruit students all over the world to code for the organizations' long-expected features.

This year (2017), Frescobaldi participates in it and decides to set Add Support for Version Control (Git) as one of the topics of the two projects. Wen Xin(@wenxin-bupt), a student from Beijing University of Posts and Telecommunications(China) is selected to work in full time to implement the features in his proposal. Urs Liska(@uliska) mentors him during this period.

Wen Xin (@wenxin-bupt) contributes 195 commits for Frescobaldi during GSoC. You can find the all the commits and most of the discussions of this project in PR #974 WIP: Rewrite vcs . (Edit by Urs Liska: the concrete state at the time of submission can be seen by the tag GSoC-2017-Git-submission.

What you can see now

The accomplished features of this project bring basic Git diff functionalities into Frescobaldi. To experience these new features, run Frescobaldi from Git (follow this guide, only Linux is supported) and then check out into rewrite-vcs branch.

When editing an already committed file in Frescobaldi, you will find all the added lines are marked by a green "✚" symbol and orange "◆" for modified lines, red "━" for deleted lines.

With a right click on the diff symbol, a popup window appears displaying the diff result (HEAD vs. Working) of current hunk of code. And by clicking the revert button, you can revert this hunk back to committed state.

The file's git status is displayed in bottom and it gets updated in real time while editing.

• In lyfiles on master -- lyfiles is the name of the repository, master is current branch's name
• File is modified -- current file's status
• 65+ -- 65 lines have been new added to this file

How the code is organized

This is the call structure of the major related classes (click here to check for the original picture). The blocks with green background color are implemented during GSoC.

Functionalities of the new modules

• /frescobaldi_app/vcs/

  • abstractdoc.py: Abstract class Document(), which is inherited by the Document() in gitdoc.py
  • abstractrepo.py: Abstract class Repo(), which is inherited by the Repo() in gitrepo.py
  • gitdoc.py: Class Document(), its instances are used to track files in Git repository
  • gitrepo.py: Class Repo(), its instances are used to track Git repositories. Class RepoManager(), its instance manages all the Git Repo() instances. Frescobaldi has only one instance of (Git) RepoManager() during running.
  • manager.py: Class VCSManager(), its instance manages every vcs's RepoManager() (Git, Hg, svn, currently only Git is supported)
  • helper.py: Provides Helper Class for every VCS(currently only GitHelper() is fully implemented)
  • differ.py: Provides several functions to generate HTML formatted diff contents used by VCSDiffWindow()

• /frescobaldi_app/widgets/

  • vcsdiffarea.py: QWidget VCSDiffArea(), a widget beside the line-number widget in Frescobaldi. It shows the diff status of the changed lines with different symbols.
  • vcsdiffwindow.py: QWidget VCSDiffWindow(), a popup window displays the diff contents.

Completion status of the original plan

Here are the features listed in original plan. Those marked by √ have been implemented.

• Git command module. A module providing the git command interface for other modules. Including the following functionalities.

  • a pure git command function.
    • cross-platform support
    • encode-decode support
    • asynchronous execution support
  • basic git operations
    • get current branch
    • get current working file's git status
    • git diff (working vs Index, working vs HEAD, Index vs HEAD)
    • git commit

• Working view, Index view and HEAD view

  • three views of current file and corresponding music views.

• Git info

  • display current file's git status: untracked, unmodified, modified, staged, staged modified
  • display current branch

• Git diff in gutter (Working vs. Index, Working vs. HEAD, Index vs. Working)

  • Working vs. HEAD in Working view
  • Working vs. Index in Working view
  • Index vs. Working in Index view
  • implement a new widget in sidebar rather than changing the number-area module

• Git diff inline

  • extract the modified and deleted lines from "git diff" output and display them inline in the editor

• Git diff inline editor (Working view)

  • users can partially (in line or hunk) stage changes in Working view
  • users can partially (in line or hunk) discard changes in Working view
  • "Ctrl + z" undo operation support (natively supported by QPlainTextEdit)

• Git diff inline editor (Index view)

  • users can partially (in line or hunk) unstage changes in Working view
  • "Ctrl + z" undo operation support

• Git commit

  • provide a pop out window listing the staged files and asking for commit message for commit operation
  • optional: display git diff in a meaningful way

Note

Wen Xin (@wenxin-bupt) has been in close contact with his mentor Urs Liska (@uliska) about the still unfinished features. Urs Liska (@uliska) is completely fine with it.

Summary and prospect

More than half of the features in original plan have been implemented in GSoC period. On GUI, Git diff in line and the popup diff window have been implemented and tested. And current work will be merged soon in future. To accomplish this project's original purpose, the rest of features will be implemented after the GSoC's end. Wen Xin (@wenxin-bupt) is willing to continue working on this project.