Git for ArduPilot
Git is a free and open source distributed version control system that is used to manage ArduPilot codebase. Git is available on all major OS platforms, and a variety of tools exist to make it easier to get started.
Managing the code is important as the project get more complex. It would be helpful to see the changes and enhance reliablity. So let us get start! I will use Ubuntu, the operation in MAC, Windows can be found on official guide!
Installing Git on Ubuntu
sudo apt-get update sudo apt-get install git sudo apt-get install gitk git-gui
In order to keep dev enviorment is same as the orgin org, dev in ubuntu!
sign up for a free user account with Github
open a web browser and go to github.com/ArduPilot/ardupilot
“Cloning” is git’s term for making a local copy of a remote repository (i.e. one held on the GitHub servers).
open a terminal and navigate to the directory where you would like the clone to be stored
clone your fork:
git clone https://github.com/your-github-userid/ardupilot cd ardupilot git submodule update --init --recursive
Branches are a way to isolate different paths of development, which can then be combined (aka “merged”) into a single branch (often named “master”). Refer to this short guide or the resources in the Learning Git section for more information.
Commits record changes to the code along with a description and the author’s name.
Branching and Committing (Git ready)
open a terminal window and cd to the ardupilot directory of your clone and checkout the master branch
git checkout master
the new branch will be a copy of the current branch so ensure your clone’s master branch is up-to-date with (aka rebased on) ArduPilot/master. If you have just forked and cloned your repo then it should already be up-to-date.
decide on a branch name and create the new branch. The name is up to you but it can be helpful to choose a short descriptive name. The branch name used for this tutorial is “apm_git_tutorial.
git checkout -b apm_git_tutorial
Change some code. For this tutorial, open the Tools/GIT_Test/GIT_Success.txt in your preferred text editor, and put your name at the end of the file then save the file
See that you have changed the files by checking the status
- Stage and Commit your work to the branch to record your changes to your clone
git add Tools/GIT_Test/GIT_Success.txt git commit -m 'Tools: added name to GIT_Success.txt'
In this case, the subject line of the commit is simply “Tools: added name to GIT_Success.txt” but see here for more detailed information on conventions for commits that you expect to be integrated into ArduPilot/master.
Push the new branch from your local clone to your fork on GitHub. This will copy your work on your local branch to a new branch on GitHub. Pushing branches is a precondition for collaborating with others on GitHub or for submitting patches back to the official releases. It is assumed “origin” is the remote name of your fork on GitHub
git push origin HEAD:apm_git_tutorial
Congratulations! This is bulk of the normal process you’d follow when working on code to submit back to the official project. The next step is to submit a pull request so your changes can be considered for addition to the main project.
“Rebasing” allows you to update a branch from ArduPilot’s master branch and then re-apply any changes you may have made to the branch.
- Navigate to your ardupilot git repository.
- Starting from here we will assume that you want to rebase your topic-branch on ArduPilot master branch. This process is the same for the master branch, just replace topic-branch with master. Ensure you are looking at your master branch or the branch that you want to rebase.
git checkout topic-branch
- If you want to create a new branch to work on which you would like to rebase on top of the ArduPilot master branch,
git checkout -b topic-branch
- Ensure your repository is connected to the upstream repository you forked from.
git remote add upstream https://github.com/ArduPilot/ardupilot.git
- Fetch changes from the upstream repository (this simply downloads changes into a local cache, it will not overwrite or modify your changes in any way). If you are rebasing your branch on your own fork’s master branch, replace upstream with origin
git fetch upstream
- Rebase your current branch from the upstream’s master branch.
git rebase upstream/master
- Update your local repo’s submodules
git submodule update --recursive
- Check that the rebase was successfull. Using cmdline (git log --oneline --decorate --all --graph , type q to exit) or a GUI tool like gitk, sourcetree, etc. Your commits should appear on top of ArduPilot master lastest commit, like show on previous picture.
- Now push the updated branch to your github repository
git push origin topic-branch
Diffcult for me, make life easy!
ArduPilot uses a single level of git submodules, with all modules stored in the modules directory. This approach was chosen as it makes for diagnosis of issues with submodules simpler. This means that if an external project (i.e. PX4Firmware) has submodules of its own, those submodule appear directly in the ArduPilot modules directory.
7.11 Git Tools - Submodules
Updating your local repo’s submodules
To manually update submodules use the following command
git submodule update --recursive
- Very occasionally a new submodule is added to ArduPilot, after which every developer must run this command:
git submodule init
Ardupilot.org. (2019). Installing Git — Dev documentation. [online] Available at: https://ardupilot.org/dev/docs/git-install.html [Accessed 13 Jan. 2020].
Quaranto, N. (2020). git ready » branching and merging. [online] Gitready.com. Available at: http://gitready.com/beginner/2009/01/25/branching-and-merging.html [Accessed 13 Jan. 2020].
Git-scm.com. (2019). Git - Submodules. [online] Available at: https://git-scm.com/book/en/v2/Git-Tools-Submodules [Accessed 13 Jan. 2020].