|
| 1 | +# Usage |
| 2 | +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. |
| 3 | + |
| 4 | + - [A Command Line tool](usage/commandLine.md) |
| 5 | + - [An MSBuild Task](usage/msbuildTask.md) |
| 6 | + - [A NuGet Library package](#NuGet-Library) |
| 7 | + - [A Ruby Gem](#Gem) |
| 8 | + |
| 9 | +## Command Line |
| 10 | +If you want a command line version installed on your machine then you can use [Chocolatey](http://chocolatey.org) to install GitVersion |
| 11 | + |
| 12 | +Available on [Chocolatey](http://chocolatey.org) under [GitVersion.Portable](http://chocolatey.org/packages/GitVersion.Portable) |
| 13 | + |
| 14 | + > choco install GitVersion.Portable |
| 15 | + |
| 16 | +Switches are available with `GitVersion /?` |
| 17 | + |
| 18 | +### Output |
| 19 | +By default GitVersion returns a json object to stdout containing all the [variables](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. |
| 20 | + |
| 21 | +`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](buildServers.md) for more information about this. |
| 22 | + |
| 23 | + |
| 24 | +## MSBuild Task |
| 25 | +The MSBuild task will wire GitVersion into the MSBuild pipeline of a project and automatically stamp that assembly with the appropriate SemVer information |
| 26 | + |
| 27 | +Available on [Nuget](https://www.nuget.org) under [GitVersionTask](https://www.nuget.org/packages/GitVersionTask/) |
| 28 | + |
| 29 | + Install-Package GitVersionTask |
| 30 | + |
| 31 | +Remove the `Assembly*Version` attributes from your `Properties\AssemblyInfo.cs` file. Sample default: |
| 32 | + |
| 33 | + [assembly: AssemblyVersion("1.0.0.0")] |
| 34 | + [assembly: AssemblyFileVersion("1.0.0.0")] |
| 35 | + [assembly: AssemblyInformationalVersion("1.0.0.0")] |
| 36 | + |
| 37 | +Make sure there is a tag somewhere on master named `v1.2.3` before `HEAD` (change the numbers as desired). Now when you build: |
| 38 | + |
| 39 | +* AssemblyVersion will be set to 1.2.0.0 (i.e Major.Minor.0.0) |
| 40 | +* AssemblyFileVersion will be set to 1.2.3.0 (i.e Major.Minor.Patch) |
| 41 | +* AssemblyInformationalVersion will be set to `1.2.4+<commitcount>.Branch.<branchname>.Sha.<commithash>` where: |
| 42 | + * `<commitcount>` is the number of commits between the `v1.2.3` tag and `HEAD`. |
| 43 | + * `<branchname>` is the name of the branch you are on. |
| 44 | + * `<commithash>` is the commit hash of `HEAD`. |
| 45 | + |
| 46 | +Continue working as usual and when you release/deploy, tag the branch/release `v1.2.4`. |
| 47 | + |
| 48 | +If you want to bump up the major or minor version, create a text file in the root directory named NextVersion.txt and inside of it on a single line enter the version number that you want your next release to be. e.g., `2.0`. |
| 49 | + |
| 50 | +### Why is AssemblyVersion only set to Major.Minor? |
| 51 | + |
| 52 | +This is a common approach that gives you the ability to roll out hot fixes to your assembly without breaking existing applications that may be referencing it. You are still able to get the full version number if you need to by looking at its file version number. |
| 53 | + |
| 54 | +### My Git repository requires authentication. What do I do? |
| 55 | + |
| 56 | +Set the environmental variables `GITVERSION_REMOTE_USERNAME` and `GITVERSION_REMOTE_PASSWORD` before the build is initiated. |
| 57 | + |
| 58 | +## NuGet Library |
| 59 | +To use GitVersion from your own code. |
| 60 | + |
| 61 | +**Warning, we are not semantically versioning this library and it should be considered unstable.** |
| 62 | + |
| 63 | +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. |
| 64 | + |
| 65 | +## Gem |
| 66 | +Just a gem wrapper around the command line to make it easier to consume from Rake. |
| 67 | + |
| 68 | +**NOTE** This is currenly not being pushed.. Please get in touch if you are using this |
| 69 | + |
| 70 | +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. |
| 71 | + |
| 72 | + gem install gitversion |
| 73 | + |
| 74 | +The gem comes with a module to include in your Rakefile: |
| 75 | + |
| 76 | +```ruby |
| 77 | +require 'git_version' |
| 78 | + |
| 79 | +include GitVersion |
| 80 | + |
| 81 | +puts git_version.sha |
| 82 | +``` |
| 83 | + |
| 84 | +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. |
| 85 | + |
| 86 | +gitversion internally caches the JSON output, so `GitVersion.exe` is only called once. |
| 87 | + |
| 88 | +Any arguments passed to `git_version` will be passed to `GitVersion.exe`: |
| 89 | + |
| 90 | +```ruby |
| 91 | +require 'git_version' |
| 92 | + |
| 93 | +include GitVersion |
| 94 | + |
| 95 | +puts git_version('C:/read/info/from/another/repository').sha |
| 96 | +``` |
| 97 | + |
| 98 | +**Note:** Mono is not currently supported due to downstream dependencies on libgit2. The Gem can only be used with the .NET framework |
0 commit comments