Skip to content

Commit 0551e1e

Browse files
JakeGinnivanJakeGinnivan
committed
Merge pull request #683 from pascalberger/UsageDocImprovements
Improveme usage documentation
2 parents c5c2094 + 0a90ea2 commit 0551e1e

File tree

7 files changed

+176
-173
lines changed

7 files changed

+176
-173
lines changed

‎docs/usage.md

Lines changed: 0 additions & 172 deletions
This file was deleted.

‎docs/usage/command-line.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Command Line
2+
3+
If you want a command line version installed on your machine then you can use [Chocolatey](http://chocolatey.org) to install GitVersion
4+
5+
Available on [Chocolatey](http://chocolatey.org) under [GitVersion.Portable](http://chocolatey.org/packages/GitVersion.Portable)
6+
7+
> choco install GitVersion.Portable
8+
9+
Switches are available with `GitVersion /?`
10+
11+
## Output
12+
13+
By default GitVersion returns a json object to stdout containing all the [variables](more-info/variables.md) which GitVersion generates. This works great if you want to get your build scripts to parse the json object then use the variables, but there is a simpler way.
14+
15+
`GitVersion.exe /output buildserver` will change the mode of GitVersion to write out the variables to whatever build server it is running in. You can then use those variables in your build scripts or run different tools to create versioned NuGet packages or whatever you would like to do. See [build servers](build-server-support.md) for more information about this.
16+
17+
## Inject version metadata into the assembly
18+
`GitVersion.exe /updateassemblyinfo` will recursively search for all `AssemblyInfo.cs` files in the git repo and update them.
19+
It will update the following assembly attributes:
20+
21+
* `AssemblyVersion` will be set to the `AssemblySemVer` variable.
22+
* `AssemblyFileVersion` will be set to the `MajorMinorPatch` variable with a appended `.0`.
23+
* `AssemblyInformationalVersion` will be set to the `InformationalVersion` variable.
24+
25+
Note that contrary to when using the [MSBuild Task](msbuild-task.md) the attributes must already exist in the `AssemblyInfo.cs` files prior to calling GitVersion.
26+
27+
By adding `/updateassemblyinfofilename` the name of AssemblyInfo file to update can be set.

‎docs/usage/gem.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Gem
2+
3+
Just a gem wrapper around the command line to make it easier to consume from Rake.
4+
5+
**NOTE** This is currently not being pushed.. Please get in touch if you are using this
6+
7+
If you want a Ruby gem version installed on your machine then you can use [Bundler](http://bundler.io/) or [Gem](http://rubygems.org/) to install the `gitversion` gem.
8+
9+
gem install gitversion
10+
11+
The gem comes with a module to include in your Rakefile:
12+
13+
```ruby
14+
require 'git_version'
15+
16+
include GitVersion
17+
18+
puts git_version.sha
19+
```
20+
21+
Internally, this will call the `GitVersion.exe` that is bundled with the Ruby gem, parse its JSON output and make all the JSON keys available through Ruby methods. You can either use Pascal case (`git_version.InformationalVersion`) or Ruby-style snake case (`git_version.informational_version`) to access the JSON properties.
22+
23+
gitversion internally caches the JSON output, so `GitVersion.exe` is only called once.
24+
25+
Any arguments passed to `git_version` will be passed to `GitVersion.exe`:
26+
27+
```ruby
28+
require 'git_version'
29+
30+
include GitVersion
31+
32+
puts git_version('C:/read/info/from/another/repository').sha
33+
```
34+
35+
**Note:** Mono is not currently supported due to downstream dependencies on libgit2. The Gem can only be used with the .NET framework

‎docs/usage/msbuild-task.md

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# MSBuild Task
2+
3+
Available on [Nuget](https://www.nuget.org) under [GitVersionTask](https://www.nuget.org/packages/GitVersionTask/)
4+
5+
Install-Package GitVersionTask
6+
7+
The MSBuild task will wire GitVersion into the MSBuild pipeline of a project and perform several actions.
8+
9+
## Inject version metadata into the assembly
10+
11+
Task Name: `GitVersionTask.UpdateAssemblyInfo`
12+
13+
### AssemblyInfo Attributes
14+
15+
At build time a temporary AssemblyInfo.cs will be created that contains the appropriate SemVer information. This will will be included in the build pipeline.
16+
17+
Ensure you remove the `Assembly*Version` attributes from your `Properties\AssemblyInfo.cs` file so as to not get duplicate attribute warnings. Sample default:
18+
19+
[assembly: AssemblyVersion("1.0.0.0")]
20+
[assembly: AssemblyFileVersion("1.0.0.0")]
21+
[assembly: AssemblyInformationalVersion("1.1.0+Branch.master.Sha.722aad3217bd49a6576b6f82f60884e612f9ba58")]
22+
23+
Now when you build:
24+
25+
* `AssemblyVersion` will be set to the `AssemblySemVer` variable.
26+
* `AssemblyFileVersion` will be set to the `MajorMinorPatch` variable with a appended `.0`.
27+
* `AssemblyInformationalVersion` will be set to the `InformationalVersion` variable.
28+
29+
### Other injected Variables
30+
31+
All other [variables](more-info/variables.md) will be injected into a internal static class.
32+
33+
```
34+
namespace AssemblyName
35+
{
36+
[CompilerGenerated]
37+
internal static class GitVersionInformation
38+
{
39+
public static string Major = "1";
40+
public static string Minor = "1";
41+
public static string Patch = "0";
42+
...All other variables
43+
}
44+
}
45+
```
46+
47+
### Accessing injected Variables
48+
49+
**All variables**
50+
51+
```
52+
var assemblyName = assembly.GetName().Name;
53+
var gitVersionInformationType = assembly.GetType(assemblyName + ".GitVersionInformation");
54+
var fields = gitVersionInformationType.GetFields();
55+
56+
foreach (var field in fields)
57+
{
58+
Trace.WriteLine(string.Format("{0}: {1}", field.Name, field.GetValue(null)));
59+
}
60+
```
61+
62+
**Specific variable**
63+
64+
```
65+
var assemblyName = assembly.GetName().Name;
66+
var gitVersionInformationType = assembly.GetType(assemblyName + ".GitVersionInformation");
67+
var versionField = gitVersionInformationType.GetField("Major");
68+
Trace.WriteLine(versionField.GetValue(null));
69+
```
70+
71+
## Populate some MSBuild properties with version metadata
72+
73+
Task Name: `GitVersionTask.GetVersion`
74+
75+
At build time all the derived [variables](more-info/variables.md) will be written to MSBuild properties so the information can be used by other tooling in the build pipeline.
76+
77+
The class for `GitVersionTask.GetVersion` has a property for each variable. However at MSBuild time these properties a mapped to MSBuild properties that are prefixed with `GitVersion_`. This prevents conflicts with other properties in the pipeline.
78+
79+
### Accessing variable in MSBuild
80+
81+
After `GitVersionTask.GetVersion` has executed the properties can be used in the standard way. For example:
82+
83+
<Message Text="GitVersion_InformationalVersion: $(GitVersion_InformationalVersion)"/>
84+
85+
## Communicate variables to current Build Server
86+
87+
Task Name: `GitVersionTask.WriteVersionInfoToBuildLog`
88+
89+
If, at build time, it is detected that the build is occurring inside a Build Server server then the [variables](more-info/variables.md) will be written to the build log in a format that the current Build Server can consume. See [Build Server Support](build-server-support.md).
90+
91+
## My Git repository requires authentication. What do I do?
92+
93+
Set the environmental variables `GITVERSION_REMOTE_USERNAME` and `GITVERSION_REMOTE_PASSWORD` before the build is initiated.

‎docs/usage/nuget-library.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# NuGet Library
2+
3+
To use GitVersion from your own code.
4+
5+
**Warning, we are not semantically versioning this library and it should be considered unstable.**
6+
7+
It also is not currently documented. Please open an issue if you are consuming the library to let us know, and why you need to.

‎docs/usage/usage.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Usage
2+
3+
There are two main ways to consume GitVersion, the first is by running GitVersion.exe. The second is an MSBuild task. The MSBuild task is really easy to get up and running, simply install GitVersionTask from NuGet and it will integrate into your project and write out variables to your build server if it's running on one. The exe offers more options and works for not just .net projects.
4+
5+
- [A Command Line tool](command-line.md)
6+
- [An MSBuild Task](msbuild-task.md)
7+
- [A NuGet Library package](nuget-library.md)
8+
- [A Ruby Gem](gem.md)

‎mkdocs.yml

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,12 @@ repo_url: https://github.com/GitTools/GitVersion
44

55
pages:
66
- Home: index.md
7-
- Usage: usage.md
7+
- Usage:
8+
- Usage: usage/usage.md
9+
- Command Line: usage/command-line.md
10+
- MSBuild Task: usage/msbuild-task.md
11+
- NuGet Library: usage/nuget-library.md
12+
- Gem: usage/gem.md
813
- Build Server Support: build-server-support.md
914
- Configuration: configuration.md
1015
- Examples: examples.md

0 commit comments

Comments
 (0)