sbt-git
The sbt-git
plugin offers git command line features directly inside sbt as
well as allowing other plugins to make use of git.
Installation
Latest:
Add the following to your project/plugins.sbt
or ~/.sbt/0.13/plugins/plugins.sbt
file:
addSbtPlugin("com.typesafe.sbt" % "sbt-git" % "0.8.5")
Prior to sbt 0.13.5:
Add the following to your project/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)
Using JGit
If you do not have git installed and available on your path (e.g. you use windows),
make sure your git.sbt
or ~/.sbt/0.13/git.sbt
file looks like this:
useJGit
Or you can type this into the prompt:
> set useJGit
[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:...)
This will enable a java-only GIT solution that, while not supporting all the same commands that can be run in the standard git command line, is good enough for most git activities.
Versioning with Git
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:
- Looks at version-property setting (default to
project.version
), and checks thesys.props
to see if this has a value. If so, use it. - Otherwise, looks at the project tags. The first to match the
gitTagToVersionNumberSetting
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 no tags are found either, look at the head commit. We attach this to the
git.baseVersion
setting: "<base-version>.<git commit sha>" - 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>".
The git.baseVersion
setting represents the in-development (upcoming) version you're working on.
You can alter the tag-detection algorithm using the git.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 using git describe
command by adding:
git.useGitDescribe := true
This way the version is derived by passing the result of git describe
to the gitTagToVersionNumber
function. The describe
version is built from the last tag + number of commits since tag + short hash. We recommend adopting the git describe approach.
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" }
Prompts
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)
Usage
In an sbt prompt, simply enter any git command. e.g.
> git status
# On branch master
# 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")
Licensing
This software is licensed under the BSD license.