Tutorial preparing to work with github

From Let's Control It
Jump to navigation Jump to search

In order to work with git and github, you'll need some one time preparation.

This may seem a bit of work, but it makes contributing to ESPEasy much easier for everyone.

Note: If you dont need to contribute your changes back to ESPEasy, its also possible to just download the zip file: https://github.com/letscontrolit/ESPEasy/releases and then you can skip ahead to this tutorial: Tutorial_building_and_uploading_with_platformio

Creating a github.com account

If you plan to contribute to the ESP Easy project with code you need to have a GitHub account, if not skip to Tutorial building and uploading with platformio. If you don't have a github account yet, create one for free here: https://github.com/join?source=hero-opensource

  • Choose the “Unlimited public repositories for free” option.
  • Go to your email and click the verify link.

Forking the ESPEasy repository

To be able to make changes and share them with us, you will need to fork our repository one time.

  • Login to your github.com with your account.
  • Go the the letscontrol ESPEasy repository, via https://github.com/letscontrolit/ESPEasy
  • Make sure you're in the correct repository and click the fork button in the upper right corner:

Espeasy fork button.png

Now you have forked the ESPEasy repository to your own github account:

Espeasy own fork.png

Its important to set default branch to the one you want to contribute to (currently mega), otherwise Github Desktop will not clone the submodule automaticly.: Github default branch.png

Now that you've forked ESPEasy to your own github account, you can start making improvements or fixes and send them to us via a pull request.

To be able to do that you need a tool to clone the files to your local computer, and to send the changes back to your github repository.

You can clone your repository to as many computers as you like. In fact: its a great way to make sure you're changes to the sourcecode on different computers doesn't get lost.

Installing Github Desktop

The easiest way to work with github if you're new is with Github Desktop. (there are many other opensource alternatives if you're more experienced with git)

With this tool you can clone the ESPEasy repository to your own pc, make changes, and send those changes back to github.

  • Download Github Desktop:

Download github desktop.png

  • Start the installer and click though it:

Install github desktop.png

  • Desktop will start automaticly with the welcome screen. Login with your github.com account:

Gitdesktop login.png

  • The configure step is usually ok:

Gitdesktop configure.png

  • Skip the Repositories step:

Gitdeskapp skip local.png

Now you can clone your forked repository to your local computer.

Cloning ESPEasy to your computer

Note: Its important you set the default branch on Github to the correct one (currently mega), otherwise Github Desktop will not clone the submodules.

  • In GitHub Desktop Click the + in the upper left corner
  • Click the Clone tab
  • Select the ESPEasy repository:

Gitdesktop clone.png

  • Click Clone ESPEasy
  • Select a place where you want to store the ESPEasy sourcecode
  • ESPEasy will be cloned to your computer:

Cloning espeasy.png

  • Your now have the ESPEasy sourcecode on your computer:

Gitdesktop cloned.png

Now you’re ready to make some changes, compile them, and send them back to use when you're ready.

To learn how to do this go to the next step: Tutorial_building_and_uploading_with_platformio