Code Collaboration#
This section describes the use of Git and Github in relation to standard Tudat developer use cases. This chapter does not serve as a complete tutorial on Git, but rather as common practices with fundamentals of the Git workflow (or Gitflow) used by a Tudat Developer.
Note
Git comes with the Anaconda and Miniconda distributions by default. If you are using Conda, then Git is already available in your Conda command-line interface (specific to your OS).
Audience |
Prerequisite(s) |
Time |
Git Beginner |
~ 10 minutes |
Learning Objectives
Understand the differences between Git and Github.
Clone and manage repositories from Github.
Understand the Tudat Git workflow.
Make your first contribution to Tudat.
Cloning a Repository#
Cloning a repository is a straightforward process. Each repository on GitHub has a green Code button. After clicking this button, you can then choose to “Clone with HTTPS” by clicking the clipboard icon under the dropdown and executing:
git clone <repository_url>
The primary version of the repository source code will be cloned.
Note
The master
branch has commonly served as this primary version of a
repository, though Github has changed this default to main
in recent
times in an effort to align with political correctness. master
and
main
will be used interchangeably in this document, where images or
repositories have not been updated.
Todo
Update all graphics, documentation and repositories to the new default main
.
Try it yourself!
After entering your desired directory with the cd
command, clone the
developer-primer
repository [2]:
$ git clone https://github.com/tudat-team/developer-primer.git
You now have a local repository set to the main
branch of the remote
developer-primer repository 🎉
developer-primer
├── .authors
│ ├── AUTHORS
│ ├── .authors.yml
│ └── .mailmap
├── bibtex.bib
├── CHANGELOG.rst
├── docs
│ ├── build
│ ├── make.bat
│ ├── Makefile
│ └── source
├── environment.yaml
├── .gitignore
├── LICENSE
├── news
│ └── TEMPLATE.rst
├── README.rst
├── rever.xsh
└── source
└── tree_trunk.txt
There’s a lot going on in the Repository structure, don’t be overwhelmed. By the end of the Primer, you will have all the knowledge required to navigate it like a pro Tudat Developer.
Develop and Master Branches#
Instead of a single master
branch, this workflow uses two branches to record
the history of the project. The master
branch stores the official release
history, and the develop
branch serves as an integration branch for features.
It’s also convenient to tag all commits in the master
branch with a version
number. [3]
The first step is to complement the default master
with a develop
branch. A
simple way to do this is for one developer to create an empty develop
branch
locally and push it to the server (remote):
git branch develop
git push -u origin develop
Note
The -u
flag simply tells Git to track the newly created remote branch.
This branch will contain the complete history of the project, whereas master
will contain an abridged version. Other developers should now clone the central
repository and create a tracking branch for develop
. If you form part of
this group, (i.e. a develop
branch already exists on the remote) you can
create a tracking branch for develop
by executing:
git checkout --track origin/develop
A tracking branch simply means that you have a local version of a branch that is connected to an existing remote version. This relationship is invaluable as it provides two major benefits:
- Pushing and pulling becomes a lot easier.
git push origin develop
replaced by shorthandgit push
git pull origin develop
replaced by shorthandgit pull
Git will now inform you about “unpushed” and “unpulled” commits.
Try it yourself!
With the developer-primer
repository [2]
cloned, check what branches exist on the remote:
$ git branch -r
origin/HEAD -> origin/main
origin/develop
origin/main
You can think of the HEAD
as the “current branch”. The output above shows
that there there is indeed a develop
branch available on the remote.
Let’s create a local tracking branch:
$ git checkout --track origin/develop
Branch 'develop' set up to track remote branch 'develop' from 'origin'.
Switched to a new branch 'develop'
Congratulations, you are now on your local version of the develop
branch, which is tracking the remote version of develop
🎉
Feature Branches#
Each new feature should reside in its own branch, which can be pushed to the
central repository for backup/collaboration. But, instead of branching off of
master
, feature
branches use develop
as their parent branch. When a
feature is complete, it gets merged back into develop
. Features should
never interact directly with master
. [3]
Note
Note that feature
branches combined with the develop
branch is, for
all intents and purposes, the Feature Branch Workflow. But, the Gitflow
Workflow doesn’t stop there. Feature
branches are generally created off
to the latest develop
branch.
Creating a feature branch#
$ git checkout develop
$ git checkout -b feature/name
$ git flow feature start feature_name
Continue your work and use Git as demonstrated beforehand.
Try it yourself!
With the developer-primer
repository [2],
ensure that the develop
branch is checked out, and create a new local
feature branch with your Github username as the feature name.
$ git checkout develop
Already on 'develop'
Your branch is up to date with 'origin/develop'.
$ git checkout -b feature/ggarrett13_was_here
Switched to a new branch 'feature/ggarrett13_was_here'
After creating a feature that is appropriate for the planned work, carry
out the work! Just for sake of example in modifying the source
of a
project, carve “<your_github_name> was here!” to the tree
trunk contained in the source directory, using the command:
Note
This is just some arbitrary example “work” of modifying a projects source code for sake of example, not a convention or standard.
$ echo "ggarrett13 was here!" >> source/tree_trunk.txt
Your message will be appended to the bottom of the tree_trunk.txt
:
----- This is a tree trunk -----
ggarrett13 was here!
Stage source/tree_trunk.txt
to be committed:
$ git add source/tree_trunk.txt
Finally, commit the changes made to your feature branch:
$ git commit -m "ggarrett13 was here!"
[feature/ggarrett13_was_here 6810969] ggarrett13 was here!
1 file changed, 1 insertion(+)
You’re all set to leave your first mark on the Tudat Space community.
Finishing a feature branch#
When you’re done with the development work on the feature, the next step is to
merge the feature/name
into develop
.
$ git checkout develop
$ git merge feature/name
Try it yourself!
Continuing with the developer-primer
repository [2],
checkout the develop
branch in your local repository and merge your
feature into it.
$ git checkout develop
Switched to branch 'develop'
Your branch is up to date with 'origin/develop'.
$ git merge feature/ggarrett13_was_here
Updating e2285f3..6810969
Fast-forward
source/tree_trunk.txt | 1 +
1 file changed, 1 insertion(+)
Finally, push the changes to the remote:
$ git push
Counting objects: 4, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (4/4), 364 bytes | 364.00 KiB/s, done.
Total 4 (delta 1), reused 0 (delta 0)
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
To https://github.com/tudat-team/developer-primer.git
e2285f3..6810969 develop -> develop
Congratulations, you’ve just officially made your first mark on the Tudat Space community as a Tudat Developer! 🎉
Release Branches#
Todo
Complete Release Branches section. Currently not a common part of the Tudat Developer workflow, but will be soon!
Hotfix Branches#
Todo
Complete Hotfix Branches section. Currently not a common part of the Tudat Developer workflow, but will be soon!
Chapter Summary
Gitflow Workflow [3]
A
develop
branch is created frommaster
A
release
branch is created fromdevelop
Feature
branches are created fromdevelop
When a
feature
is complete it is merged into thedevelop
branchWhen the
release
branch is done it is merged intodevelop
andmaster
If an issue in
master
is detected ahotfix
branch is created frommaster
Once the
hotfix
is complete it is merged to bothdevelop
andmaster