Difference between revisions of "Bering-uClibc 4.x - Developer Guide - Hints and Tips for using Git SCM"

From bering-uClibc
Jump to: navigation, search
(Expanded and general tidy-up)
m (Corrected note about "git clone" versus "git-clone")
Line 39: Line 39:
 
To actually create a copy of the SourceForge-hosted repository change to a suitable directory on your build host and run the following command:
 
To actually create a copy of the SourceForge-hosted repository change to a suitable directory on your build host and run the following command:
 
  git clone ssh://''USERNAME''@leaf.git.sourceforge.net/gitroot/leaf/leaf
 
  git clone ssh://''USERNAME''@leaf.git.sourceforge.net/gitroot/leaf/leaf
'''Note:''' All of the "git" commands can be entered as e.g. "git clone" or "git'''-'''clone". The man pages use the latter naming style (with the hyphen).
+
'''Note:''' The "git" commands must be entered as e.g. "git clone" (argument "clone" to command "git") but you will also see references to e.g. "git'''-'''clone" in the documentation. This is because the man pages use the latter naming style (with the hyphen).
  
 
This creates a new directory "<tt>leaf</tt>" under the current directory which contains a full copy of the "<tt>leaf</tt>" repository on SourceForge.
 
This creates a new directory "<tt>leaf</tt>" under the current directory which contains a full copy of the "<tt>leaf</tt>" repository on SourceForge.

Revision as of 15:09, 5 February 2011

Hints and Tips for using Git SCM
Prev Bering-uClibc 4.x - Developer Guide


Background

The LEAF project successfully used the CVS (Concurrent Version System) Source Code Management (SCM) tool, hosted by SourceForge, for many years. Various developers suggested switching to an alternative SCM such as Subversion or Git (see in particular the email thread "Talks about versioning system" on the leaf-devel mailing list in late September 2010) but the consensus was that CVS met all the basic requirements and a change of SCM would only divert resources away from other more important tasks.

The consensus view changed in late January / early February 2011, when the SourceForge systems were compromised and CVS proved particularly difficult to restore (see the SourceForge report here). In particular, the indication was that the SourceForge-hosted CVS service would be retired.

The SourceForge-hosted Git SCM service was selected as the new SCM for Bering-uClibc 4.x early in February 2011.


Getting Started

Browse using GitWeb

The very first step is probably to browse the web-based interface to the SourceForge-hosted Git repository at the LEAF project GitWeb to familiarize yourself with the structure.

Install the Git Client

The next step is to ensure you have the Git client software installed on your build host. On Red Hat-derived Linux distributions this is accomplished with:

yum install git

Clone the SourceForge-hosted Git Repository

Next, you will want to copy ("clone") the SourceForge-hosted Git repository. The naming convention for project repository URLs is documented on the SourceForge Git page. In our case "PROJECTNAME" = "leaf" and "REPONAME" = "leaf" so the repository is accessed as:

Read-only 
git://leaf.git.sourceforge.net/gitroot/leaf/leaf
Read-write 
ssh://USERNAME@leaf.git.sourceforge.net/gitroot/leaf/leaf

The examples that follow assume you want read-write access and will therefore use the second (ssh) variant. Obviously you need to replace "USERNAME" with your own SourceForge username. You will be prompted to enter your SourceForge account password when using the "ssh" URL, or you can configure SSH keys as described here.

To actually create a copy of the SourceForge-hosted repository change to a suitable directory on your build host and run the following command:

git clone ssh://USERNAME@leaf.git.sourceforge.net/gitroot/leaf/leaf

Note: The "git" commands must be entered as e.g. "git clone" (argument "clone" to command "git") but you will also see references to e.g. "git-clone" in the documentation. This is because the man pages use the latter naming style (with the hyphen).

This creates a new directory "leaf" under the current directory which contains a full copy of the "leaf" repository on SourceForge. Change to this new "leaf" directory for the following steps:

cd leaf

Configure your User Identity

Any changes you make are identified with your user details as specified in a Git configuration file. To populate these on a repository-specific basis run the following commands:

git config user.name "Your Full Name"
git config user.email "USERNAME@users.sourceforge.net"

Tip: Review the contents of file .git/config to see where these setting are maintained and what else is in this file.

Change an Existing File

That's all of the preparation complete; now we can actually change something. The following examples show an update to bering-uclibc4/buildtool/conf/sources.cfg.

Edit the file

First change to the directory containing the file to be modified:

cd bering-uclibc4/buildtool/conf

Modify the file using your favourite text editor:

edit sources.cfg

Tell Git about the changes

When the modifications are complete you need to tell Git about them. This is accomplished using the "git add" command:

git add sources.cfg

Note: With CVS you would only "add" new files or directories. With Git you need to also need to "add" changes to existing files.

Running "git add" has the effect of adding the differences in the specified file(s) to a local "index" of pending changes which is then processed by a subsequent "git commit" transaction.

Commit the changes to the local Git repository

At any point you can review the contents of the "index" of pending changes with the following command:

git diff --cached

It is good practice to always do this before running "git commit".

Next, you need to commit the changes to your local Git repository:

git commit -m "Log message for changes"

Note: With CVS this would commit the changes directly to the shared repository on SourceForge however with Git the "commit" command only commits the changes to the local Git repository.

Publish the changes to the SourceForge-hosted Git repository

Publishing the local changes to the shared Git repository hosted on SourceForge needs a further step:

git push

Tip: All of the "git" commands take a "--dry-run" command-line parameter. This processes the command as normal but does not actually update the repository. Use this while you are learning to check what effect a command will have before running it for real.


Git Command Reference for CVS Users

For developers familiar with CVS, here are the equivalent Git commands for some basic SCM tasks:

Task CVS Command Git Command
Check-in a modified file cvs commit -m "Log Message" filename git add filename; git commit -m "Log Message"; git push


Further Reading



Prev Up