Managing the code base

To obtain and manage the nRF Connect SDK code base, you must use a combination of Git and west.

As described in nRF Connect SDK code base, the nRF Connect SDK contains the following repositories:

  • The manifest repository, sdk-nrf. This repository is managed by the user using Git exclusively, since west will not modify or update it in any way. The exception to this is the west init command, which can clone the manifest repository automatically at an arbitrary revision.

  • The west projects. Those are listed in the manifest repository’s west.yml manifest file. They are entirely managed by west, which will clone them or check out a specific revision of them every time you run west update.

Obtaining a copy of the nRF Connect SDK

To obtain a fresh copy of the nRF Connect SDK at revision {revision} and place it in a folder named ncs, use the following commands:

west init -m https://github.com/nrfconnect/sdk-nrf --mr {revision} ncs
cd ncs
west update

Replace {revision} with any revision you wish to obtain. This can be master if you want the latest state, or any released version (e.g. v1.4.0). If you omit the --mr parameter, west defaults to master.

Updating a copy of the nRF Connect SDK

If you already have a copy of the nRF Connect SDK and wish to update it or switch to a new revision, then you only need to do the following:

cd ncs/nrf
git fetch {remote}
# Check out the latest master branch
git checkout {remote}/master
# or check out a release
git checkout {revision}
west update

Where {remote} is the Git remote that points to the official Nordic repository. This is called origin by default for the sdk-nrf repository and ncs for most others, but may have another name. You can use git remote -v to list all your remotes.

Note that using git checkout is one of multiple ways of achieving this. Git offers several commands and mechanisms to set the current working copy of a repository to a particular revision. Depending on how you manage the branches of your local clone of the sdk-nrf repository, you can also replace the use of git checkout with, among many others:

# If you have no changes of your own
git reset --hard {remote}/master
git reset --hard {revision}
# If you have changes of your own
git rebase {remote}/master
git rebase {revision}

Describing the exact differences between the commands above is outside the scope of this section. Refer to the publicly available Git documentation.

Forking a repository of the nRF Connect SDK

In some cases, you might want to keep a soft fork of one or more repositories that are part of the nRF Connect SDK. The procedure to achieve that is the same regardless of whether you fork the manifest repository and/or one or more project repositories.

There are two similar but slightly different meanings to the term “fork”, as described in the Glossary:

  • A fork in general terms is a server-hosted copy of an upstream repository with a few downstream changes on top of it. It can be hosted on GitHub or elsewhere.

  • A GitHub fork is GitHub’s mechanism to copy an existing repository and then send Pull Requests from it to the upstream repository.

A GitHub fork can be used to send Pull Requests and to act as a regular long-lived fork in general terms. You can also create standard forks with GitHub by just creating an empty repository first and then initializing it with the contents of the upstream repository you wish to fork.

Note

About Git remotes: The default name for a remote is origin but you can pick any arbitrary name for a remote. By convention, the following remote names are typically used:

  • origin usually points to the user’s personal copy of the repository.

  • ncs is used to point to the nRF Connect SDK repository.

  • upstream typically points to the upstream repository, when applicable.

The west init command creates a remote named origin that points to the original location of the cloned manifest repository. The west update command, on the other hand, uses the remote: property in the west.yml file to name the remote pointing to the original location.

If you want to create a GitHub fork follow the steps below:

  1. Create a GitHub fork using the Fork button in the GitHub user interface.

  2. Add the newly created remote repository as a Git remote:

    cd ncs/{folder_path}
# Rename the default remote from 'origin' to 'ncs', if required
git remote rename origin ncs
git remote add origin https://github.com/{username}/{repo}.git

    For example, to create a fork of the sdk-nrf repository for GitHub user foo:

    cd ncs/nrf
# The manifest repository defaults to a remote named 'origin'
git remote rename origin ncs
git remote add origin https://github.com/foo/sdk-nrf.git

    If you were to fork an OSS repository instead, which itself is already a fork of the original upstream project:

    cd ncs/zephyr
# No need to rename the remote, since it will already be named 'ncs'
git remote add origin https://github.com/foo/sdk-zephyr.git
git remote add upstream https://github.com/zephyrproject-rtos/zephyr.git

That way you would actually have three remotes, each pointing to the relevant copy of the Zephyr codebase:

To create a regular fork, follow the exact same steps as above, but the actual repository must be created by you beforehand, instead of clicking Fork in GitHub. Also, since a GitHub fork automatically initializes the forked repository with the exact same contents as the original one, you must push the contents yourself:

cd ncs/{folder_path}
# Rename the default remote from 'origin' to 'ncs'
git remote rename origin ncs
git remote add origin https://github.com/{username}/{repo}.git
git push origin master