vDiff - A Diff for Versioned Methods

vDiff generates a diff of a file's versioned methods. To perserve legacy code, we may implement a change to hello01() by copying it and adding the change in a new method hello02(). Now we won't introduce any bugs in legacy, but we won't be able to easily see the change in the source control's diff. However, vDiff will comb through a file and create a diff between the two methods.

How to use

• Configure your file's versioning by defining its methodPattern in settings. The first perl example shown is configured by default.
• Right click on your active editor or a file in the explorer and select Version Diff

Customizing your signature

Currently the signature pattern should consist of two capture groups. The first capture group is expected to be the method's identifier. This is what matches two different versions together. The second is the version.

"vdiff.methodPatterns": [
  {
    ...,
    "signature": "sub $NAME$$VERSION$\\s",
    "name": "[A-Za-z_]*",
    "version": "(\\d{4})(\\d{2})(\\d{2})"
  }
]

"vdiff.methodPatterns": [
  {
    ...,
    "signature": "public .* $NAME$_$VERSION$\\(.*\\)",
    "name": "[A-Za-z_]*",
    "version": "(\\d{2})_(\\d{2})_(\\d{4})
  }
]

Extracting your version

"vdiff.methodPatterns": [
  {
    ...,
    "version": "(\\d{4})(\\d{2})(\\d{2})",
    "formattedVersion:":"Year: $1 | Month: $2 | Day: $3"
  }
]

Version Type

Setting your version type (and versionDateFormat if the type is date) is very important as it orders the methods determining which one is new and old. The default value is text.

"vdiff.methodPatterns": [
  {
    ...,
    "versionType": "number"
  }
]

"vdiff.methodPatterns": [
  {
    ...,
    "versionType": "date",
    "versionDateFormat": " "mm_yyyy" // required with date versionType
  }
]

Comparing between files

"vdiff.methodPatterns": [
  {
    ...,           
    "compareWith": [
        "__greetings__.pm"
    ],
  }
]

Using Regex

Regex is a sequence of characters that specifies a search pattern in text. It is used heavily in this extension to find versioned methods and to extract information about them. If you are new to regex, I would recommend using a regex testing website like https://regex101.com/ to test if your regex matches your methods' signatures when configuring your settings.

Here is also a cheat sheet: https://quickref.me/regex#regex-in-javascript

The regex expression in your settings should be for javascript regex. Not the language you are trying to parse.

The regex in the settings comes in as a string, so the proper escape characters must be included. That is why in the examples you will see "\d" instead of "\d".

Settings

Method Patterns

Method patterns are the regex or string templates for parsing versioned methods

Here is the configuration for the example gif

"vdiff.methodPatterns": [
  {
    "filetype": ".pm", // The file extension that this pattern applies to
    "signature": "sub $NAME$$VERSION$\\s", // Regex expression that matches a method signature, with a capture group for the name and version
    "name": [A-Za-z_]*, // the identifier that matches the method
    "version": "(\\d{4})(\\d{2})(\\d{2})", // Regex expression for grabbing the version, with capture groups that are supplied to "versionExtraction" to add a comment
    "formattedVersion: "$2/$3/$1", // The template "version" uses to add an inline comment describing the version
    "description": "(^(?:#.*\\n)+)", // Regex expression for grabbing the comments before a method. 
    "versionType": "number" // the version type, it can be number, text, or date.
  }
]

You can add more method patterns to support other file types or version configurations