PlatformIO Community

New user with Git repo clone problems

Hi, I have recently installed vsscode and platformio, I have got to a stage where I can create open, edit and save my projects. So next step is version control and I use Git, so I was pleased to see that I can clone a Git repo. However, I have the problem described below when cloning my Git repo:

from platformio quick access, i picked Clone Git Repo and provided a target folder in the platformio projects:


I made some small test changes, then used the available commands to stage and commit. All went well on the git commands front, but:

When I closed vsscode and returned later to open the ‘stepper’ project I got the message that it wasn’t a platformio project because there was no platformio.ini, so I copied one from another of my projects into the ‘stepper’ folder and closed vsscode.

When I start vsscode and goto platformio home to open the project, it now opens fine but when I try to compile it I get the error ‘nothing to build’ and the problem indicated is that the source code needs to be in

Probably prior to cloning my git repo I need to change the folder structure to accommodate the platformio folder structure? Would that help? Or should platformio provide the structure when it clones the repo?

I’m just aware that there are other folders in platformio structure :

and I’m likely to fall foul again if I don’t have them.

If I include the folders will platformio populate them automatically?

thanks for help,

Hi @paulskirk53,

The PlatformIO project structure is reasonably mandatory, although src is where your main source file(s) are expected to be, you can change this using the src_dir = whatever where whatever is a folder, I think within, your project’s main folder. (I haven’t used a non-default structure, yet!)

If you don’t have src, or if there are no *.cpp files in it (or in whatever src_dir points to), nothing will compile.

A platformio.ini file is a necessity for a folder to be considered a PlatformIO project.

Further info on structure etc, by @maxgerhardt, on this thread

Oops! I’ve just noticed that’s your thread!



thanks Norman, I played around with my local repo structure to include a src folder in which I now store the cpp file. I pushed that, then used Git clone in platformio. It seems to work ok, at least the code compiles now. I had to change my gitignore to include the following directory excludes:

because there were 142 changes showing (where I’d made none in the source), so I assumed it was from files within these folders.

Just in case it’s helpful to others, I’ve described below what I had and the process I’ve used to migrate to using platformIO

I used to use the Arduino IDE (and also some others but no consequence here) and had an Arduino projects folder:

C:\Arduino Projects

This folder contained folders for my projects e.g. C:\Arduino Projects\Stepper

and each project folder was initialised as a Git repo. and contained a source.ino and a gitignore.

So when I’d finished using the Arduino IDE to make code changes, I’d close it and then run git bash (if i needed command line) or more frequently Github Desktop to commit and push changes to origin

Now when I moved to vsscode and platformio, I found that to use platformios git clone feature effectively, I needed to change the repo structure and push it before I used the platformio git clone for the first time. Here’s the new structure inside C:\Arduino Projects\Stepper

src (this now contains the source code - in my case stepper.cpp)
platformio.ini (required for this to be recognised as a platformio project)
.gitignore (see below for inclusions)

I changed the gitignore to include the following directory excludes:

Back in vsscode and platformio, I can now clone the repo and I use C:\users\paul\documents\platformio\projects as the clone target folder (this is the standard platformio structure). Once the clone is complete the project can be opened. I found commit and push all worked fine from within platformio.

When moving from the arduino IDE and .ino files to .cpp, note that functions have to be declared within the source as per the guide here:

The above process worked for me and I’ll update the thread if I find any further changes are required.

I am a farly light Git user, so there may be a better way than I chose to achieve the above.

thanks for help,

Indeed. When you create a new project – I tend to use the command line:

pio init --board uno`

PlatformIO creates a default .gitignore file. It only contains .pio at the moment. Adding the .vscode might be a useful addition?

The above command creates the following structure:

├── include
│   └── README
├── lib
│   └── README
├── platformio.ini
├── src
└── test
    └── README

When you compile for the first time, a .pio will be created and this is where the source is compiled into (.pio/build/<environment>) along with the various libraries, if used (.pio/build/libXXXX/<library_name> – so all those files will be considered untracked by git and it will flag them up in VSCode for your attention.

Your Arduino sketches can be easily migrated to the above structure. You have a couple of options:

  • Bung everything related to the sketch into src, change the *.ino files to *.cpp and add #include "Arduino.h" to the main file(s). That way you get a quick Arduino sketch but using C++ filenames which gives you “intellisense” when open in VSCode. (*.ino files don’t have intellisense, but you will get annoying prompts to search the matrketplace for helpers – don’t!).

  • Bung the main *.ino file into src as a cpp file, and add the above #include, then shove every other file into lib.

  • Rewrite the whole sketch using AVR C++ rather than Arduino Language stuff! :grin:

Thanks for the write up, I’m sure it will come in handy for other “beginners”.


thanks Norm, have you got a good link to intro to AVR C++?

I’m having another problem when compiling. I have a program which uses the Liquid crystal library and I installed that from platformio home. It seemed to instal fine - I had the ‘congrats’ message. However, when I try to compile, I get this error below related to wire dependency. I assume installing a lib installs the dependencies? thanks for your help.

Executing task: C:\Users\Paul\.platformio\penv\Scripts\pio.exe run <

Processing megaatmega2560 (platform: atmelavr; board: megaatmega2560; framework: arduino)
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------Verbose mode can be enabled via `-v, --verbose` option
CONFIGURATION: (i had to remove the url here as the forum objected)
PLATFORM: Atmel AVR (3.1.0) > Arduino Mega or Mega 2560 ATmega2560 (Mega 2560)     
HARDWARE: ATMEGA2560 16MHz, 8KB RAM, 248KB Flash
DEBUG: Current (avr-stub) On-board (avr-stub, simavr)
 - framework-arduino-avr 5.1.0
 - toolchain-atmelavr 1.50400.190710 (5.4.0)
LDF: Library Dependency Finder ->
LDF Modes: Finder ~ chain, Compatibility ~ soft
Found 7 compatible libraries
Scanning dependencies...
Dependency Graph
|-- <AccelStepper> 1.61.0
|-- <LiquidCrystal> 1.5.0
Building in release mode
Compiling .pio\build\megaatmega2560\lib8b6\LiquidCrystal\I2CIO.cpp.o
Compiling .pio\build\megaatmega2560\lib8b6\LiquidCrystal\LiquidCrystal_I2C_ByVac.cpp.o
Compiling .pio\build\megaatmega2560\FrameworkArduino\HardwareSerial3.cpp.o
Compiling .pio\build\megaatmega2560\FrameworkArduino\IPAddress.cpp.o
Compiling .pio\build\megaatmega2560\FrameworkArduino\PluggableUSB.cpp.o
.pio\libdeps\megaatmega2560\LiquidCrystal\I2CIO.cpp:54:21: fatal error: Wire.h: No such file or directory
Compiling .pio\build\megaatmega2560\FrameworkArduino\Print.cpp.o

* Looking for Wire.h dependency? Check our library registry!
* CLI  > platformio lib search "header:Wire.h"
* Web  > Compiling .pio\build\megaatmega2560\FrameworkArduino\Stream.cpp.o .pio\build\megaatmega2560\FrameworkArduino\Tone.cpp.o


compilation terminated.
Compiling .pio\build\megaatmega2560\FrameworkArduino\USBCore.cpp.o
In file included from .pio\libdeps\megaatmega2560\LiquidCrystal\LiquidCrystal_I2C_ByVac.cpp:46:0:
Compiling .pio\build\megaatmega2560\FrameworkArduino\WInterrupts.c.o
.pio\libdeps\megaatmega2560\LiquidCrystal\LiquidCrystal_I2C_ByVac.h:56:21: fatal error: Wire.h: No such file or directory
Compiling .pio\build\megaatmega2560\FrameworkArduino\WMath.cpp.o

* Looking for Compiling .pio\build\megaatmega2560\FrameworkArduino\WString.cpp.o
Wire.h dependency? Check our library registry!

Write either Wire in the list of lib_deps dependencies in the platformio.ini or #include <Wire.h> in your main C++ source file to trigger the inclusion of the library.

ah thanks, so adding a library does not install that libraries dependencies. Perhaps there’s a setting somewhere…


just read the documentation page about library installation and it isn’t quite clear about whether a libraries dependent libraries will be installed.


That one is tricky. PlatformIO and its library dependency finder (LDF) has a few quirks. In general, if a library properly declares its dependencies in its meta-information, the library.json, they will be installed. If PlatformIO notices an inclusion like #include <Wire.h> in the source code inside src/, it will automatically pick it up as a dependency. Some includes / dependencies may however be declared in library code and not in its manifest, or worse, surrounded by macros which at compile-time can include a file or not. The LDF does its best but sometimes has to be set to a more aggressive mode (lib_ldf_mode).

This library here, judging from the version number, is (which is also not the official version: That is published by Arduino/Adafruit at The library you’ve chosen does have a library.json but fails to declare its Wire dependency.

C:\Users\Max\.platformio\>pio lib  -g install "bitbucket-fmalpartida/LiquidCrystal@^1.5.0"
C:\Users\Max\.platformio\lib\LiquidCrystal>cat library.json
    "name": "LiquidCrystal",
    "keywords": "lcd, hd44780",
    "description": "LiquidCrystal Library is faster and extensable, compatible with the original LiquidCrystal library",
    "authors": {
        "name": "F Malpartida",
        "url": ""
      "type": "hg",
      "url": ""
    "version": "1.5.0",
    "exclude": ["def", "thirdparty libraries", "utility/docs", "doxygen*"],
    "frameworks": "arduino",
    "platforms": "atmelavr,espressif8266,espressif32"

(no dependencies attribute).

So when the library is not declaring it, and there’s no direct #include <Wire> in the source file, and the LDF is set to its default not-so-agressive mode, the LDF might not pick it up and you have to help it a little by declaring the dependency yourself. So it really depends on the library (especially the manifest json file) and the code.

In general, for a new library, add it as normal to the platformio.ini in the lib_deps (or use the PIO Home GUI) and include its main header file in your source file, nothing more. If it compiles, all is good. If it fails, you need to help it.

many thanks for this comprehensive reply. How does one tell if a library is the ‘official one’ or not?

best wishes

Well with “official” I just meant that it’s from a well-known organization or company, like

  • the Arduino organization itself, the owner is then also arduino-libraries
  • Adafruit (
  • Sparkfun (
  • a microcontroller company

And that that version is not “official” because it’s a modification of a “official” library by an individual (also stated in the library description).

The author is always shown in the library information page along with the repo link


The other one is


And the repository link is also dead.

There only a few libraries anyways which have “unofficial spinoffs”, like this LiquidCrystal library. Others are just made by one party. After a while you get a feeling for what’s the “official” library and what’s a fork. Such libraries also usually have it in their description text if it’s a fork. E.g. “LiquidCrystal Library is faster and extensable, compatible with the original LiquidCrystal library” is directly in the description text of the first library.

Here are a couple of decent links:

But probably best is the book Make: AVR Programming by Elliot Williams. It covers the ATmega168 but that’s pretty much the same as the ATmega328, just half the SRAM/Flash RAM.

There is another book, which covers an introduction to converting from Arduino to AVR, but modesty prevents me from mentioning it! :wink:

Don’t forget the ATmega328P Data Sheet - it’s hard going at first, and covers everything about the device, and most things have example code in C/C++ and assembler.

Other books in my collection:



brill, thanks Norm, much appreciated, I’ll have a look for your book converting from Arduino to AVR too.

If you get the Elliott Williams one, you won’t need mine. :grin: He covers it all. Mine has a short introduction as it’s a bit of an aside.