HOWTO use Git instead of Mercurial - Revision history

Tomh at 23:53, 15 June 2022

2022-06-15T23:53:17Z

← Older revision		Revision as of 23:53, 15 June 2022
Line 1:		Line 1:
	{{TOC}}		{{TOC}}

	The ns-3 project presently uses Mercurial as its source code control system, but several developers favor using Git. Git is a VCS like Mercurial, Subversion or CVS, and it used to maintain many open-source (and closed-source) project. While git and mercurial have a lot of common properties, if you are new to git you should read first an introduction to it. The most up-to-date guide is the [https://git-scm.com/book/en/v2/Getting-Started-Git-Basics Git Book].		'''Note:''' Mercurial is no longer used so this HOWTO is obsolete

			The ns-3 project <s>presently uses Mercurial as its source code control system</s>, but several developers favor using Git. Git is a VCS like Mercurial, Subversion or CVS, and it used to maintain many open-source (and closed-source) project. While git and mercurial have a lot of common properties, if you are new to git you should read first an introduction to it. The most up-to-date guide is the [https://git-scm.com/book/en/v2/Getting-Started-Git-Basics Git Book].

	Ns-3 project has set up a mirror on Github at https://github.com/nsnam/ns-3-dev-git.		Ns-3 project has set up a mirror on Github at https://github.com/nsnam/ns-3-dev-git.

Mohit at 08:02, 18 July 2016

2016-07-18T08:02:01Z

← Older revision		Revision as of 08:02, 18 July 2016
Line 1:		Line 1:
	{{TOC}}		{{TOC}}

	The ns-3 project presently uses Mercurial as its source code control system, but several developers favor using Git. Git is a VCS like Mercurial, Subversion or CVS, and it used to maintain many open-source (and closed-source) project. While git and mercurial have a lot of common properties, if you are new to git you should read first an introduction to it. The most up-to-date ~~guite~~ is the [https://git-scm.com/book/en/v2/Getting-Started-Git-Basics Git Book].		The ns-3 project presently uses Mercurial as its source code control system, but several developers favor using Git. Git is a VCS like Mercurial, Subversion or CVS, and it used to maintain many open-source (and closed-source) project. While git and mercurial have a lot of common properties, if you are new to git you should read first an introduction to it. The most up-to-date guide is the [https://git-scm.com/book/en/v2/Getting-Started-Git-Basics Git Book].

	Ns-3 project has set up a mirror on Github at https://github.com/nsnam/ns-3-dev-git.		Ns-3 project has set up a mirror on Github at https://github.com/nsnam/ns-3-dev-git.

Natale at 09:00, 14 April 2016

2016-04-14T09:00:09Z

← Older revision		Revision as of 09:00, 14 April 2016
Line 236:		Line 236:

	Please remember that rewriting already published history is '''bad''', especially if someone other has synced your commits into their repository, but is necessary if you want to make clear commits. As a general rule, your personal development history can be rewritten as you wish; the history of your published features should be kept as they are.		Please remember that rewriting already published history is '''bad''', especially if someone other has synced your commits into their repository, but is necessary if you want to make clear commits. As a general rule, your personal development history can be rewritten as you wish; the history of your published features should be kept as they are.

			== Collaborating: an example of exchange between a maintainer and a contributor ==
			In the following we will explain a typical git workflow in the case of an exchange between a maintainer (M) and a contributor (C). It's clear that M is the only one that can push over the official ns-3-dev repo; but sometime, commits from C should be reviewed and tested out-of-the-tree. Now, we will follow two paths, corresponding to the actions of C and the actions of M.

			=== How a contributor could made commits to be reviewed by a maintainer ===

			The first step for C is to set up a fork of the official ns-3-dev-git repository (see before). Then, if the M has it own repository, with some branches dedicated to future work that can be included next in the ns-3-dev repository, C should add its remote and fetch the index:

			git remote add [name] [url]
			git fetch [name]

			For instance, let's assume we are working on TCP. Nat usually has his own "next-to-be-pushed" work in the branch "tcp-next" of his repo on github. Therefore, C should start its work from this branch.

			git remote add nat https://github.com/kronat/ns-3-dev-git
			git fetch
			git checkout -b [feature_name] nat/tcp-next

			Please note that this is an example; the repo name, address, and the branch name could be different. At this point, the (local) branch of C called [feature_name] is tracking nat/tcp-next, and so it has all the same commits. C can start to work, using the normal workflow.

			When the set of commit is ready, C can push the branch to its own repository. Just do:

			git push

			NO ! This will likely results in an error, since C does not have the permission into writing the M repo. C should create a new branch in his own repository:

			git push -u origin [feature_name]

			That command will change the upstream reference, setting it to your origin (which is likely your github repo), and pushing all the work into the remote "origin". For a visual representation of what is happening:

			<nowiki>
			[commit 169] <----- C/tcp-next
			.... ( work of C on tcp-next )
			[commit 160] <----- nat/tcp-next
			.... (previous work on TCP)
			[commit 123] <---- ns-3-dev-git
			... (official ns-3 history)
			</nowiki>

			Well, at this point C could notify M: "Please, see my work at github.com/C/ns-3-dev-git in the branch [feature_name]!" and maybe asking for a merge. And it's time to change the perspective, passing to M.

			=== A maintainer with a lot of contributor ===

			M has been notified of the work of C. The first thing he has to do is to adding the C repository to his (long) list of remotes:

			git remote add [C_name] [C_repo]
			git fetch [C_name]

			Then, he could quickly view the work done by the contributor:

			git checkout -b [local_C_name] [C_name]/[C_branch]

			If M thinks the work is well-done and ok, he could directly merge it into his branch:

			git checkout tcp-next
			git checkout merge [local_C_name]

			At this point, after some time, if the works is ok M should push the changes to the ns-3-dev mercurial repo. This is really tedious, and should be done carefully.. And it will be explained later in this HOWTO. But, as it often happens, M could made comments, and then wait another patchset.

			git checkout master
			git branch -D [local_C_name]

			=== A quick flash-back to C ===

			Often the maintainer will made changes to that branch, because works of other contributor could have been merged, or whatever. So, C should be ready to _REBASE_ his own branch. Please note that a maintainer is forced to merge the contributor's work, because otherwise will broke the history of many. But each single contributor should rebase his work on the maintainer branch (or the master if the maintainer has no one). So, please go back and re-read carefully the section for rebasing the work.

			=== Pushing things to ns-3-dev mercurial repository ===

			Of course this applies only for maintainers. When you have a local branch (e.g. tcp-next) that is ready to be merged in ns-3-dev, please do the following:
			# Pull the ns-3-dev-git master into your master branch
			# Rebase your local tcp-next branch to your local master branch
			# Create a series of patch that applies on top of master:
			git format-patch master
			# Copy these patches in ns-3-dev mercurial repo
			# Apply and commit one-by-one all these patches, paying attention to the right owner of the commit.

			One last thing: for binary patches this doesn't work: you need to update by hand all the files. We still need to figure a way to export correctly binary patches from git to mercurial.

	== Cheat sheet ==		== Cheat sheet ==

Natale: Expanded and introduced a lot of new concepts

2016-01-17T13:56:59Z

Expanded and introduced a lot of new concepts

Show changes

Teto: Explain how to add upstream remote

2016-01-15T13:13:43Z

Explain how to add upstream remote

← Older revision		Revision as of 13:13, 15 January 2016
Line 9:		Line 9:
	== Forking ==		== Forking ==

	Assume that you are user '~~johnqexample~~' on github, and that you want to create a new public github repo that is synced to nsnam/ns-3-dev-git.		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.

	#. Log into github		#. Log into github
Line 38:		Line 38:
	== Syncing your fork ==		== Syncing your fork ==

	To keep your fork synced with nsnam/ns-3-dev-git, take these steps from within your local clone:		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 fetch upstream
Line 82:		Line 86:
	git diff master > patch-against-master.patch		git diff master > patch-against-master.patch

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

	git clean -df		git clean -df
	git checkout -- .		git checkout -- .

Tomh: start a git howto

2016-01-14T20:06:23Z

start a git howto

New page

{{TOC}}

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 [https://help.github.com/articles/using-pull-requests/ pull requests] at this time; to contribute back to the mainline code, use our bug tracker or Rietveld (see [https://www.nsnam.org/developers/contributing-code/ 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 'johnqexample' on github, and that you want to create a new public github repo that is synced to nsnam/ns-3-dev-git.

#. Log into github
#. Navigate to https://github.com/nsnam/ns-3-dev-git
#. 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.

#. Under your repository name, click Settings.
#. Under the Repository Name heading, type the new name of your repository.
#. 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 ==

To keep your fork synced with nsnam/ns-3-dev-git, 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 ==

git clean -df
git checkout -- .