Repository files navigation

Thesbt-git plugin offers git command line features directly inside sbt aswell as allowing other plugins to make use of git.

This plugin is community maintained. Seesbt#182 if you'd like to help.

As of1.0.0 this plugin requires at leastJava 8.The latest version supporting Java 7 was0.9.3, while the latest version supporting Java 6 was0.8.5.

Latest:

Add the following to yourproject/plugins.sbt or~/.sbt/1.0/plugins/plugins.sbt file:

addSbtPlugin("com.github.sbt" % "sbt-git" % "<version>")

Prior to sbt 0.13.5:

Add the following to yourproject/plugins.sbt or~/.sbt/0.13/plugins/plugins.sbt file:

addSbtPlugin("com.typesafe.sbt" % "sbt-git" % "0.7.1")

additionally, use one of the older README.md files: (https://github.com/sbt/sbt-git/blob/v0.7.1/README.md)

JGit is a Java interface to git that allows some git operations to beperformed in the JVM without invoking an external git executable. By default,this plugin uses JGit for read-only operations such as inspecting HEAD; forwrite operations, it assumes a git executable is present and on the PATH andit uses that.

In certain circumstances you may want to force the use of JGit or anexecutable for both read-only and read-write operations; for example, if nogit executable is present (e.g. you use windows and you haven't installed gitor it's not on your PATH) you need to disable the console interface, or ifyou rely on a git feature that JGit does not support (e.g. worktrees) you needto disable the JGit interface.

The following settings will force the use of only JGit or a git executable,respectively:

• useJGit
• useReadableConsoleGit

These settings can be included in your project'sgit.sbt or in~/.sbt/1.0/git.sbt -- for example, if no git executable is installed,either file can have the following contents:

useJGit

Or you canset the appropriate setting in the sbt prompt:

> set useReadableConsoleGit[info] Reapplying settings...[info] Set current project to scala-arm (in build file:...)> session save[info] Reapplying settings...[info] Set current project to scala-arm (in build file:...)

You can begin to use git to control your project versions.

enablePlugins(GitVersioning)

The git plugin will now autogenerate your version using the following rules, in order:

1. Looks at version-property setting (default toproject.version), and checks thesys.props to see if this has a value. If so, use it.
2. Otherwise, looks at the project tags. The first to match thegitTagToVersionNumberSetting is used to assign the version. The default is to look for tags that begin withv and a number, and use the number as the version. If there are multiple version tags, it will pick the highest.
3. If no tags are found either, look at the head commit. We attach this to thegit.baseVersion setting: "<base-version>.<git commit sha>"
4. If no head commit is present either (which means this is a brand-new repository with no commits yet), we append the current timestamp to the base version: "<base-version>.<timestamp>".

Thegit.baseVersion setting represents the in-development (upcoming) version you're working on.

You can alter the tag-detection algorithm using thegit.gitTagToVersionNumber setting. For example, if we wanted to alter the default version tag detection so it does not require a "v" at the start of tags, we could add the following setting:

git.gitTagToVersionNumber := { tag: String =>  if(tag matches "[0-9]+\\..*") Some(tag)  else None}

You can turn on version detection usinggit describe command by adding:

git.useGitDescribe := true

This way the version is derived by passing the result ofgit describe to thegitTagToVersionNumber function. Thedescribe version is built from the last tag + number of commits since tag + short hash. We recommend adopting the git describe approach.

You can enhance the git describe approach withglob pattern matching, to match only relevant tags (as pergit describe --match functionality). This may be useful if, for example, your repository contains multiple types of tag.

git.gitDescribePatterns := Seq("module-name-*")

Additionally, you can also customize the version number generated by overriding one of the following keys:

• git.formattedShaVersion - Should look upgit.gitHeadCommit key and generate a version based on it.
• git.formattedDateVersion - The version we'll use if git is unavailable on this repository, for some reason.

As an example, you can alter the default sha-based versions using the following code

git.formattedShaVersion := git.gitHeadCommit.value map { sha => s"v$sha" }

You can use the git plugin to add the project name + the current branch to your prompt. Simply add this setting to every project:

enablePlugins(GitBranchPrompt)

In an sbt prompt, simply enter any git command. e.g.

> git status# On branch main# Changes not staged for commit:#   (use "git add <file>..." to update what will be committed)#   (use "git checkout -- <file>..." to discard changes in working directory)##modified:   build.sbt#modified:   project/plugins/project/Build.scala## Untracked files:#   (use "git add <file>..." to include in what will be committed)##src/site/no changes added to commit (use "git add" and/or "git commit -a")

When running sbt, you will see the following warnings in console:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".SLF4J: Defaulting to no-operation (NOP) logger implementationSLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

To get rid of them, you can force the SLF4J no-op binder by addinglibraryDependencies += "org.slf4j" % "slf4j-nop" % "1.7.21" to~/.sbt/0.13/plugins/plugins.sbt

Tests for this plugin are written usingsbt-scripted. Test can be executed with

sbt scripted

This software is licensed under the BSD license.