Table of Contents
GitWCRev is Windows console program which can be used to read the status of a Git working tree and optionally perform keyword substitution in a template file - another alternative could be git filters (cf. Section G.4.2, “gitattributes(5)”). This is often used as part of the build process as a means of incorporating working tree information into the object you are building. Typically it might be used to include the revision number in an “About” box.
GitWCRev reads the Git status of all files in a working tree including submodules. It records the HEAD commit revision and the commit timestamp, it also records whether there are local modifications in the working tree. The status revision and modification status are displayed on stdout.
GitWCRev.exe is called from the command line or a script, and is controlled using the command line parameters.
GitWCRev WorkingTreePath [SrcVersionFile DstVersionFile] [-mMuUsdq]
WorkingTreePath is the path to the working
tree being checked.The path may be absolute or relative to the current working directory.
If you want GitWCRev to perform keyword substitution, so that
fields like repository revision is saved to a text
file, you need to supply a template file
SrcVersionFile
and an output file
DstVersionFile
which contains the substituted version of the template.
You can specify ignore patterns for GitWCRev to prevent specific files
and paths from being considered. The patterns are read from a file
named .gitwcrevignore. The file is read from the working tree root.
If the file does not exist, no files or paths are ignored.
The .gitwcrevignore file can contain multiple
patterns, separated by newlines. The patterns are matched against
the paths relative to the repository root . For example, to ignore all
files in the /doc folder of the TortoiseGit working tree,
the .gitwcrevignore would contain the following
lines:
/doc /doc/*
To ignore all images, the ignore patterns could be set like this:
*.png *.jpg *.ico *.bmp
![[Important]](important.png)
|
Important |
|---|---|
|
The ignore patterns are case-sensitive, just like Git is. |
![[Tip]](tip.png)
|
Tip |
|---|---|
|
To create a file with a starting dot in the Windows explorer,
enter |
There are a number of optional switches which affect the way
GitWCRev works. If you use more than one, they must be specified
as a single group, e.g.
-sU, not
-s -U.
Table 3.1. List of available command line switches
| Switch | Description |
|---|---|
| -m |
If this switch is given, GitWCRev will exit with
ERRORLEVEL 7 if the working tree
contains local modifications. This may be used to
prevent building with uncommitted changes present.
|
| -M | Same as above, but includes the status of submodules. |
| -u |
If this switch is given, GitWCRev will exit with
ERRORLEVEL 11 if the working tree
contains unversioned items that are not ignored.
|
| -U | Same as above, but includes the status of submodules. |
| -d |
If this switch is given, GitWCRev will exit with
ERRORLEVEL 9 if the destination file
already exists.
|
| -s | If this switch is given, GitWCRev will exclude submodules. The default behaviour is to also check submodules. |
| -F |
If this switch is given, GitWCRev will ignore any
.gitwcrevignore files and
include all files.
|
| -q | If this switch is given, GitWCRev will perform the keyword substitution without showing working tree status on stdout. |
If there is no error, GitWCRev returns zero. But in case an error occurs, the error message is written to stderr and shown in the console. And the returned error codes are:
Table 3.2. List of GitWCRev error codes
| Error Code | Description |
|---|---|
| 1 | Syntax error. One or more command line parameters are invalid. |
| 2 | The file or folder specified on the command line was not found. |
| 3 | The input file could not be opened, or the target file could not be created. |
| 4 | Could not allocate memory. This could happen if e.g. the source file is too big. |
| 5 | The source file can not be scanned properly. |
| 6 | Git error: libgit2 returned with an error when GitWCRev tried to find the information from the working tree. |
| 7 |
The working tree has local modifications.
This requires the -m or -M switch.
|
| 9 |
The output file already exists.
This requires the -d switch.
|
| 10 | The specified path is neither a working tree nor part of one. |
| 11 |
The working tree has unversioned files or folders in it.
This requires the -u or -U switch.
|