Page tree
Skip to end of metadata
Go to start of metadata

This is a tutorial about the distributed version control system git.

The purpose of this wiki page is to provide a quick way to learn the best practices when using this tool. 

1. Installation

There are different ways to install git depending on the Operating System you are using.

For Debian based systems you can do:

sudo apt-get install git

For Red Hat based systems:

sudo yum install git

For SUSE based systems:

sudo zypper install git

 

If you want to install it on a different OS (Windows, Mac), you can find complete information here.

 

 

2. Configuration

Before starting using git, you need to configure some parameters like your account details and some other things. There are many tutorials on the internet, for example this one.

Account

There are many tutorials out here, for example here, but we will show here an example of how it could be:

git config --global user.name "Firstname Lastname"
git config --global user.email "your_email@example.com"

git review

The way collaborative open source communities work is with reviews. A patch is proposed (but not merged) and the owner has to add the desired persons to review it and give a "score" (-2, -1, 0, +1, +2).

To use this mechanism it is recommended to install the git review hook:

For Debian based systems you can do:

sudo apt-get install git-review

For Red Hat based systems:

sudo yum install git-review

For SUSE based systems:

sudo zypper install git-review

 

And then optionally run within a recently cloned repository:

git review -s

 

If you don't run this last command it is ok, when you issue a git review later for the first time on it will notice that the review hook is not installed and it will proceed to install it for the given repo.

 

 

3. Clone a repository

Using own credentials (SSH)

This is the mandatory way if you want to do modifications and propose patches. 

git clone ssh://<your_username>@gerrit.opnfv.org:29418/functest

 

Using anonymous HTTP

If you don't have an account or you don't need to push anything to the remote repository.

git clone https://gerrit.opnfv.org/gerrit/functest

 

 

4. Become a Contributor to a Project

If this is the first time you are going to submit a patch to the project you are working on, you need to get contributor rights for that project.
This can be done by sending an email to opnfv-helpdesk@rt.linuxfoundation.org and stating the project you want to contribute.

 

5. Submit a new patch

Work on a patch for the Master branch

Once you have cloned the repo as outlined in section 3 above, you can start working on it to propose a new change or a modification.

  1. Create a new development branch with a short topic (1-2 key words):
git checkout -b TOPIC-BRANCH

Once you are done with your changes, do:

git add -A
or
git add <list of files to be commited>

The commit your changes.

git commit -s

Now write your commit message. Follow the Functest best practices to have a proper commit message.

1 liner with a brief description of the patch
[blank]
JIRA issue associated with the format JIRA: FUNCTEST-X
[blank]
Extended description (optional but recommended).

For example:

 

Note that you haven't pushed anything to the remote repository yet. The commit command only does things locally.

Now it's time to publish your patch remotely. Just type:

git review

Wait a bit and you will get some output like this:

$ git review
remote: 
remote: Processing changes: new: 1, refs: 1, done 
remote: 
remote: New Changes:
remote: https://gerrit.opnfv.org/gerrit/12729 Replace all the loggers by the functest logger module
remote: 
To ssh://jose.lausuch@gerrit.opnfv.org:29418/functest.git
* [new branch] HEAD -> refs/publish/master

This command is actually an easier way of doing this:

git push origin HEAD:refs/for/master

Other branches

Although nothing should be committed directly to a stable branch, since all the bugfixes and improvements shall be cherry picked from master, sometimes it is needed. For example, to work on a patch for the branch stable/danube:

Checkout the needed branch:

git checkout -b stable/danube origin/stable/danube  # (if it is the first time)
git checkout stable/danube  # (if you already have it locally)

Do your changes as described before, but this time you need to do the following:

git push origin HEAD:refs/for/stable/danube

There are other ways using the git config file in your local repo (.git/config). Check the official documentation for more information.

 

 

6. View on Gerrit

Gerrit is the platform for repository management. This is the Functest repository: https://gerrit.opnfv.org/gerrit/#/admin/projects/functest

If you want to see your commit, go to My Changes:

and you will have the list of your own commits and others where you are added as reviewer.

There, you can give a score and publish comments or suggestions on the code itself:

NOTE: only committer rights can give a +-2 but everyone can give a +-1, normally contributors do that.

 

 

7. Work on an existing patch

Sometimes it is needed to retake an existing patch and do some more modifications and amend the patch.

If your local branch is not the one you want to work on, check it out. There are different ways, but the fastest one is having a look at the gerrit page (upper right corner):

Copy the "checkout" line to you command line or download change via git-review (and you will switch to that branch). 

git review -d change (e.g. 12665)

Now proceed with the changes you want to do and add them to the commit:

git add -A

But now, don't create a new commit, instead, amend it using:

git commit --amend

And as before, publish it:

git review

 

 

8. Merge conflicts

If you are working on a patch that modifies a specific file and some one else has merged a new version of the same file in the meanwhile, you will get a merge conflict. Git will detect it and will prevent your patch to be merged (which is completely normal).

You might get something similar to one of the following messages:

You have to resolve the conflict locally and amend a rebased patch.

When that happens, do:

git rebase master

It will complain saying something similar like thi

CONFLICT (content): Merge conflict in mydirectory/myfile.py
Auto-merging mydirectory/myfile.py
Failed to merge in the changes.

 

Now you have to edit myfile.py or whatever file with a conflict and you will see some lines like:

<<<<<<< 1466a9e5f19c9fff0503a139b22866f716a4692b

>>>>>>> <your commit message>

This is telling you what belongs to the master branch and what belongs to yours. Resolve and modify what you need. 

Now:

git add mydirectory/myfile.py  (or whatever file)
git rebase --continue
git commit --amend
git review

This will push a new patch with the resolved conflicts and you will be able to merge it.

 

  • No labels