HOWTO use Git instead of Mercurial

Main Page - Roadmap - Summer Projects - Project Ideas - Developer FAQ - Tools - Related Projects

HOWTOs - Installation - Troubleshooting - User FAQ - Samples - Models - Education - Contributed Code - Papers

The ns-3 project presently uses Mercurial as its source code control system, but several developers favor using Git. The project has set up a mirror on Github at https://github.com/nsnam/ns-3-dev-git.

Please note that this repo does not accept pull requests at this time; to contribute back to the mainline code, use our bug tracker or Rietveld (see Contributing Code to ns-3).

This page provides common tips for people who wish to fork ns-3-dev from the nsnam github repo and keep a master sync'ed to the nsnam github repo.

Forking

Assume that you are user 'john' on github, and that you want to create a new public github repo that is synced to nsnam/ns-3-dev-git.

1. . Log into github
2. . Navigate to https://github.com/nsnam/ns-3-dev-git
3. . In the top-right corner of the page, click Fork.

Note that you may only do this once; if you try to Fork again, github will take you to the page of the original fork.

To create multiple forks from the same repository, see this blog page: https://adrianshort.org/create-multiple-forks-of-a-github-repo/

For more information on forking at github: https://help.github.com/articles/fork-a-repo/

Renaming your fork

If you want to rename this repository, it is probably best to do it right after the initial fork. Let's say you wish to rename it 'ns-3-dev-wifi' to track your wifi modifications.

1. . Under your repository name, click Settings.
2. . Under the Repository Name heading, type the new name of your repository.
3. . Click Rename.

Cloning your fork

Clone it locally to your system:

 git clone https://github.com/your-user-name/ns-3-dev-git
 cd ns-3-dev-git

Syncing your fork

Git being a distributed versioning system, you are able to fetch and push changes to several repositories called "remotes". The remote you just cloned is called by default "origin" but to keep your fork synced with the official ns3, you will need to add its repository/remote:

 git remote add upstream https://github.com/nsnam/ns-3-dev-git

You can, take these steps from within your local clone:

 git fetch upstream
 git checkout master
 git merge upstream/master
 git push origin master

For more information: https://help.github.com/articles/syncing-a-fork/

Creating a branch

Now look at the available branches:

 git branch -a

you should see:

 * master
   remotes/origin/master
   remotes/upstream/master

To create a new branch

 git checkout -b [name_of_your_new_branch]

You should now see:

 git branch -a

 * master
   [name_of_your_new_branch]
   remotes/origin/master
   remotes/upstream/master
 

Creating a patch against master

If you are in a branch and want to diff it against master, you can type:

 git diff master

and redirect to a patch:

 git diff master > patch-against-master.patch

Removing all local changes not tracked in the index (Dangerous)

 git clean -df
 git checkout -- .