├── README.md ├── git-version.bat └── git-version.sh /README.md: -------------------------------------------------------------------------------- 1 | # Git-describe for Arduino 2 | 3 | This script provides an automatic versioning system for Arduino sketches based on git tag. This approach guarantees a strong relationship between source code and the compiled firmware. Moreover, it will enforce the developer to maintain meaningful tags during the project development. 4 | 5 | :information_source: **NOTE**: Currently this script is incompatible with the brand new Arduino IDE 2.x, but a [feature request](https://github.com/arduino/arduino-cli/issues/999) is already pending. 6 | 7 | ## Features 8 | 9 | - it defines the constant GIT_VERSION, visible in your source code, containing version details 10 | - No extraordinary hacking to Arduino IDE 11 | - Available for Window and Linux (MAC OS will be tested) 12 | 13 | ## Requirements 14 | 15 | - Arduino IDE 1.8.9, 1.8.11 or newer 16 | - Git 17 | 18 | > NOTE: on Arduino IDE 1.8.10 the script doesn't work because a regression bug. I didn't test this method on versions older than 1.8.9. 19 | 20 | ## Installation 21 | 22 | 1. Clone this repository (e.g. you may locate it inside `/path/to/arduino-workspace/tools/`). 23 | ``` 24 | git clone https://github.com/fabiuz7/git-describe-arduino.git 25 | ``` 26 | 27 | 2. **On Linux**, make script executable: 28 | ``` 29 | cd /path/to/arduino-workspace/tools/git-describe-arduino 30 | chmod 755 git-version.sh 31 | ``` 32 | 33 | (no need to modify global path) 34 | 35 | **On Window**, add git-version.bat to global path ([Add script to global path](https://docs.alfresco.com/4.2/tasks/fot-addpath.html)). 36 | 37 | 3. Add this script to prebuild hooks of Arduino toolchain. Created if not exist the file `platform.txt` inside `/path/to/arduino-application/hardware/`. On Windows, append the following line: 38 | ``` 39 | recipe.hooks.sketch.prebuild.1.pattern=git-version.bat "{build.source.path}/src" "{build.path}/sketch/src" 40 | ``` 41 | On Mac/Linux, append the following line: 42 | ``` 43 | recipe.hooks.sketch.prebuild.1.pattern=/path/to/arduino-workspace/tools/git-version.sh "{build.source.path}/src" "{build.path}/sketch/src" 44 | ``` 45 | 46 | ## Usage 47 | 48 | To configure your sketch you need to complete few steps: 49 | 50 | 1. Create `src` folder in the sketch folder. 51 | 2. Create `git-version.h` in `src` folder. Leave the file empty because it is overwritten by the script. 52 | 3. If your repository is not under git, initialize a reposititory for the sketch and do the first commit. 53 | 3. Modify your sketch to include `git-version.h` and print the current version. Example: 54 | 55 | ```cpp 56 | #include "src/git-version.h" 57 | 58 | void setup() { 59 | Serial.begin(115200); 60 | Serial.println(); 61 | Serial.print("Git version: "); 62 | Serial.println(GIT_VERSION); 63 | } 64 | 65 | void loop() { 66 | // put your main code here, to run repeatedly: 67 | 68 | } 69 | ``` 70 | 71 | 4. Compile and upload to see the result. Good versioning! 72 | 73 | NOTE: GIT_VERSION is a string composed by 3 dash-separated fields: 74 | 75 | - `lastest-git-tag`: printed if a tag exists 76 | - `number-of-commits-since-latest-tag`-`last-commits-short-hash`: printed if `number-of-commits-since-latest-tag` is not *0* 77 | - "dirty": printed if the working directory is dirty 78 | 79 | Example: 0.3.0-8-cc68a61-dirty 80 | 81 | ## Motivation 82 | 83 | I was working on multiple projects simultaneously and it was difficult to remember the state of applications after a few months, especially when firmware were deployed on many microcontrollers. Hence, retrieving the precise version from compiled firmware became mandatory. Also, this practice seems a rule of thumb in many toolchains and environments. This script took inspiration from similar projects such as [git-describe](https://www.npmjs.com/package/git-describe) for JavaScript and NPM and [GitInfo](https://www.nuget.org/packages/GitInfo/) for C# and Visual Studio. 84 | -------------------------------------------------------------------------------- /git-version.bat: -------------------------------------------------------------------------------- 1 | git-version.sh %1 %2 -------------------------------------------------------------------------------- /git-version.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # Script to provide automatic git-base versioning to Arduino's sketches. 4 | # Basically it runs "git describe" on source folder and creates 5 | # a file in the destination directory containg an elaborated output. 6 | # If output is not found in source directory, the script ends immediatly 7 | # without errors. 8 | # (by default, output file is named git-version.h) 9 | # 10 | # Input parameters: 11 | # 1. [Mandatory] source folder, where target files is located. It may be in subfolder of repository. 12 | # 2. [Optional] (Default value: the same as first param) path of destination directory. 13 | 14 | # Name of file that is created 15 | filename=git-version.h 16 | 17 | # Go to the source directory 18 | if [ -n "$1" ]; then 19 | cd "$1" 20 | else 21 | echo "You MUST specify the first param. Exiting..." 22 | exit 1 23 | fi 24 | echo "Executing source path = " $1 25 | 26 | if [ -f "$1/$filename" ]; then 27 | echo "$1/$filename exist" 28 | else 29 | echo "$1/$filename not exist" 30 | exit 0 31 | fi 32 | 33 | if [ -n "$2" ]; then 34 | filepath=$2/$filename 35 | #filepath=$2/$filename 36 | else 37 | filepath=./$filename 38 | fi 39 | 40 | # Build a version string with git 41 | version=$(git describe --tags --always --dirty 2> /dev/null) 42 | 43 | if [ -n "$version" ]; then 44 | echo "git version:" $version 45 | else 46 | echo "No git repo was found!" 47 | exit 1 48 | fi 49 | 50 | # If this is not a git repository, fallback to the compilation date 51 | #[ -n "$version" ] || version=$(date -I) 52 | # If this is not a git repository, create an empty file 53 | #[ -n "$version" ] || echo "" > $filename; exit 1 54 | 55 | # Save this in git-version.h 56 | echo -n "Creating file" $filepath"..." 57 | echo "#define GIT_VERSION \"$version\"" > $filepath 58 | echo " Done!" 59 | 60 | #read -p "Press key to exit..." variable1 61 | --------------------------------------------------------------------------------