[SR-Dev] [Serdev] Git Crash Course For sip-router

[Jan Janak]

Here are the attachments mentioned below.

  Jan.

On 16-04 15:54, Jan Janak wrote:
> Hello,
> 
> Here is a brief git crash course for those who are used to CVS or SVN. The
> purpose of this crash course is to get you started, it describes basic
> operations that you will need to do simple changes in the sip-router git
> repository. You can find links to more documentation at the end.
> 
> First of all, you'll need to install git. The name of the corresponding Debian
> package is git-core. Debian Lenny contains version 1.5.6.5 which is
> sufficient.  Newer git versions or packages for other distributions or
> architectures can be obtained from http://git-scm.com/.
> 
> As the second step you need to configure the git client. I have attached
> configuration files to this email for your convenience, save files .gitconfig
> and .gitignore in your home directory. File sip-router.org_CA.pem is optional,
> you will only need the file if you plan on accessing the repository over https
> (that's not the case for developers with write access). 
> 
> Edit file ~/.gitconfig and configure your name and email address there. This
> is the name and email address that will be visible in git commits. Unlike CVS
> or SVN commits, git commits contain full name and email address of the
> commiter, this is the name and email that will be visible in git history. Note
> that the email address to be used in From header of commit logs sent to the
> development mailing list is configured separately on the server (there are
> technical reasons for this). Here is how I configured my name in email address
> in ~/.gitconfig:
> 
> [user]
>     name = Jan Janak
>     email = jan at iptel.org
> 
> The git configuration file in your home directory sets up a bunch of short
> aliases for most common git commands, so you do not have to type
> 
>   $ git checkout
> 
> every time you are checking out a branch, you can just type 'git co' instead,
> and if you alias git to 'g' in your ~/.bashrc then it becomes just 'g co'
> which is much more convenient.
> 
> Another setting that is particular to our repository is the number of
> characters used for tabs in the git pager. Git uses less as the default pager
> and less is configured to use 8 spaces for tabs by default. We use 4 spaces in
> our sources and thus you might want to re-configure the git pager in your
> ~/.bashrc. The following setting makes the output of 'git diff' and friends
> look prettier:
> 
> export GIT_PAGER="less --tabs=4"
> 
> Now you can start working with git. The first command that you need to run is
> 'git clone', this is the command that is used to retrieve the sip-router
> repository from the server:
> 
>   $ git clone ssh://<username>@git.sip-router.org/sip-router
> 
> Replace <username> with your real username. The contents of the repository
> will be stored in 'sip-router' subdirectory of your current working directory.
> This command is the git equivalent of cvs/svn checkout. Like cvs/svn it will
> make the most recent version of the sources available in the
> subdirectory.
> 
> UNLIKE cvs/svn, this command does not retrieve just the latest version of the
> sources, it copies the whole history of the project to your local hard drive,
> not just the latest revision, but all revisions that are stored in the
> repository, since tday 1. You do not have to be worried about the size of
> the repository, the full history of SER takes about 40MB only.
> 
> Also, you will need to run the command only once (or occassionally if you wipe
> your local copy out entirely). There are other git commands (covered later)
> that can be used to keep your local copy up-to-date. Those commands can figure
> out the difference between your local version of the repository and the
> version on the server and they will transfer only the data that has
> changed. In other words, 'git clone' is similar to the scp command, it creates
> a local identical copy of the remote repository by copying the whole remote
> repository to the local machine.
> 
> Once you have a local copy of the sip-router repository, you can try to see
> what is in there:
> 
>   $ cd sip-router
>   $ git branch
> 
> The command above shows a list of branches that are present in your local copy
> of the repository. Most likely you will see just one branch called 'master'
> marked with an asterisk. This means that your local repository contains only
> one branch called 'master' and the asterisk tells you that this is the branch
> that is currently checked out. So the sources that you see in that directory
> come from the master branch. The local master branch is an exact copy of the
> 'master' branch from the remote repository at git.sip-router.org and it
> contains latest sip-router sources.
> 
> Typically, the branch with the most up-to-date code is called 'master' in
> git. It is the git equivalent of CVS HEAD branch and SVN trunk branch.
> 
> NOTE: Branches are sometimes called 'heads' in git documentation, but you can
> just remember that 'branch' and 'head' refers to the same thing.
> 
> If you look at the remote version of the repository with gitweb at
> http://git.sip-router.org/cgi-bin/gitweb.cgi?p=sip-router;a=heads you will
> notice that there are more branches than the 'master' branch which was created
> by 'git clone' in the local copy of the repository. The command 'git clone'
> only makes the master branch directly available in the local copy of the
> repository. For other branches it merely records the fact that the branches
> exist in the remote repository. To display branches from both the local and
> the remote repository you can run:
> 
>   $ git branch -a
> 
> The output should look roughly like this:
> 
> * master
>   origin/HEAD
>   origin/MAIN
>   origin/Maintainer
>   origin/andrei/cvshead
>   origin/andrei/sctp
>   origin/andrei/sctp_fixes
>   origin/andrei/sctp_one_to_one
>   origin/andrei_sctp
>   origin/cancel_fix
>   origin/cvs-head
>   origin/janakj/cvshead
>   origin/janakj/doxygen
>   origin/master
> 
> Branches that start with "origin/" are branches that exist in the remote
> repository. The string origin is just a short alias for the full URI of the
> remote repository, such as ssh://git.sip-router.org/sip-router. It is a
> convention that the repository you cloned from initially is called the origin.
> 
> Once you have the local repository, you can start making changes in it.
> Modifying the code on the master branch directly is really easy, because git
> clone already created the master branch for you in local repository and it
> checked out the master branch by default. Here is how can you make a simple
> change in one file and commit the result:
> 
>   $ edit main.c
>   $ git add main.c
>   $ git commit
> 
> As you can see above you need to call 'git add' before you call 'git
> commit'. 'git add' marks your changes to be commited during the next commit,
> this is useful, for example, if you want to leave some local changes
> uncommited while you make the commit. Unlike CVS or SVN, git does not assume
> that all local changes should be commited during the next commit. It lets you
> explicitly select a set of changes to be commited. You can avoid the need to
> call two commands with 'git commit -a', see the git documentation for more
> details.
> 
> When you are done with the commit, you can display the list of changes in the
> repository with 'git log'. The command displays the history of changes in the
> whole repository, if you want to limit the list to main.c only then you can
> run 'git log main.c'.
> 
> If you look closely at the output of 'git log' then you will notice strange
> lines starting with "commit" followed by a long string of characters:
> 
>  commit 0253726f99ac151f748712a5d39d71f42d9defc6
> 
> The long string is how commits in git are represented. This string is a SHA1
> checksum of the commit and it is the git equivalent SVN revision numbers. Like
> SVN revision numbers and UNLIKE CVS versions, this identifier represents the
> state of the whole repository, not just individual files. Because such long
> identifier are tedious to type, git supports abbreviated format, you can type
> just the beginning of the string as long as the beginning of the string is
> unique. In other words, there must be at most one commit in the database of all
> commits with this prefix. For example the following two commands refer to the
> same commit:
> 
>  $ git diff b0f6ec8784712e4c1436fc9a4a3b54296e94ba5c
>  $ git diff b0f6e
> 
> If somebody creates another commit with an SHA1 id starting with b0f6e later
> then 'git diff b0f6e' would not longer work and git would complain that the
> prefix is ambiguous.
> 
> All changes, such as the commit above, that you do affect the local repository
> only. There is absolutely no communication with the the remote repository in
> any of the commands above (git add, git commit, git log). This is possible
> because we created a full copy of the remote repository with 'git clone'. This
> is also the reason why all the commands are so fast, unlike their equivalents
> in CVS or SVN.
> 
> The fact that you perform all actions/modifications on the local repository
> only and then you instruct git to do its black magic and synchronize your
> local changes with the remote repository is probably the biggest difference
> from CVS/SVN and one of the things that is hard to understand for people who
> are used to CVS/SVN. This is also why git falls into the category of
> distributed revision control systems.
> 
> When you are satisfied with your local changes/commits, you can decide to make
> them available to others. This can be done by uploading your local changes to
> the remote repository (the one you initially cloned from). In git terminology
> this operation is called 'push', so you can push your local changes to the
> remote repository with 'git push':
> 
>   $ git push origin master:master
> 
> The first parameter is the name of the remote repository, the second parameter
> is the name of the local branch and the name of the remote branch, delimited
> by ':'. You can omit the 2nd parameter:
> 
>   $ git push origin
> 
> and then 'git push' will upload all local branches to the remote
> repository. You can also omit the first parameter:
> 
>   $ git push
> 
> and in that case repository 'origin' is used.
> 
> The opposite of 'git push' is 'git pull'. This is the operation that you can
> use to synchronize your local repository with the remote repository. 'git
> pull' downloads all changes (made by others) from the remote repository that
> are not yet in your local repository and integrates them into your local
> repository. You can run 'git pull' whenever you are online to fetch latest
> changes and keep your local copy of the repository up-to-date.
> 
> 'git push' and 'git pull' are similar to rsync, they update either the local
> or the remote copy of the repository by tranferring only what is missing. 'git
> push' is the git equivalent of 'cvs ci' and 'svn ci'. 'git pull' is the git
> equivalent of 'cvs update' or 'svn update'.
> 
> If you make only small changes to the repository then you can modify the
> master branch directly, as described above. This approach is suitable only for
> small, trivial changes. If are working on a change which takes longer to
> implement, consists of many commits, then it is better to create a separate
> branch and do the development on a separate branch. Branches in git are cheap,
> remember that all operations, including branch creation, are local
> operations. You do not even have to push your local branches into the remote
> repository, you can just keep them in the local copy for your own
> purposes. You can create a new branch in your local repository with 'git checkout':
> 
>   $ git checkout --track -b mybranch master
> 
> This command creates a new branch called 'mybranch', configures the branch to
> track the master branch and checks the new branch out. The word 'track' in
> this context means that the newly created branch will receive all updates from
> the master branch whenever you run 'git pull' with this branch checked out. In
> other words, the branch tracks another branch (master in this case) by merging
> all changes from the original branch. Command line option -b instructs git to
> to create a new branch. If this option was omitted then git would assume that
> 'mybranch' is an existing branch and it would try to check the branch out.
> 
> The newly created branch exists in the local repository only. If you want to
> push the branch to the remote repository then you can use 'git push' again:
> 
>   $ git push origin mybranch:janakj/mybranch
> 
> Because mybranch is a private topic branch of mine, I am pushing it as
> janakj/mybranch to the remote repository at git.sip-router.org. The remote
> repository only permits new "username" branches. In other words their name
> must start with your username. If you try:
> 
>   $ git push origin mybranch:mybranch
> 
> then git will report an error. The main reason why we have this restriction in
> place is because we wanted to make sure that people do not push all local
> branches to the remote repository by accident. This can easily happen if you
> run 'git push' without any parameters.
> 
> You can also delete a local branch that is no longer needed by running
> 
>   $ git branch -D mybranch
> 
> This will delete the local branch only. If you pushed the branch to the remote
> repository then you might also want to delete the branch in the remote
> repository with 'git push':
> 
>   $ git push :janakj/mybranch
> 
> This is a special syntax of 'git push', if you omit the name of the local
> branch then 'git push' deletes the remote branch whose name follows ':'.
> 
> Test Repository
> ===============
> We have a test repository at git.sip-router.org which you can use to test
> various git operations. Clone the repository with:
>   
>   $ git clone ssh://username@git.sip-router.org/test
> 
> and there you can test whatever you want. The repository can also be browsed
> with gitweb at
> http://git.sip-router.org/cgi-bin/gitweb.cgi?p=test;a=summary
> 
> Further Reading
> ===============
>   [1] Git related pages in the wiki: http://sip-router.org/wiki/git
>   [2] http://eagain.net/articles/git-for-computer-scientists/
>   [3] Git SVN Crashcourse: http://git.or.cz/course/svn.html
>   [4] http://git-scm.com/documentation
> _______________________________________________
> Serdev mailing list
> Serdev at lists.iptel.org
> http://lists.iptel.org/mailman/listinfo/serdev
-------------- next part --------------
-----BEGIN CERTIFICATE-----
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
smUoht97WwWBnInlJ1MBZhRTanZdjAW4s6b/aA==
-----END CERTIFICATE-----
-------------- next part --------------
[user]
	name = First Last
	email = email at address.com

[format]
	# Add the patch number and the total number of patches in the series to
	# the subject of the patch email if more than one patch is being produced.
	numbered = auto

[alias]
	cp = cherry-pick
	ci = commit
	co = checkout
	f  = fetch
	s = status
	b = branch
	d = diff
	a = add
	l = log

[color]
	branch = auto
	diff = auto
	status = auto

[http]
	# The CA certificate used to verify servers in sip-router.org domain, this
	# is useful if you pull from, for example, https://git.sip-router.org.
	#sslCAInfo = /etc/ssl/certs/sip-router.org_CA.pem

[merge]
	# Include the summary of merged commits into all newly created merge
	# commits. The newly created merge commit will contain a one-line summary
	# of every (well, most) merged commits.
	log = true

	# Show merge statistics after merge.
	stat = true

[branch]
	# When creating a new branch off a remote branch, always set it up to
	# track the remote branch so that we can pull from there.
	autoseupmerge = always

[branch "master"]
	# This is the list of cmdline options that should be added to git-merge
	# when I merge commits into the master branch. 
	#
	# First off, the option --no-commit instructs git not to commit the merge
	# by default. This allows me to do some final adjustment to the commit log
	# message before it gets commited. I often use this to add extra info to
	# the merge message or rewrite my local branch names in the commit message
	# to branch names sensible to the casual reader of the git log.
	#
	# Option --no-ff instructs git to always record a merge commit, even if
	# the branch being merged into can be fast-forwarded. This is often the
	# case when you create a short-lived topic branch which tracks master, do
	# some changes on the topic branch and then merge the changes into the
	# master which remained unchanged while you were doing your work on the
	# topic branch. In this case the master branch can be fast-forwarded (that
	# is the tip of the master branch can be updated to point to the tip of
	# the topic branch) and this is what git does by default. With --no-ff
	# option set git creates a real merge commit which records the fact that
	# another branch was merged. I find this easier to understand and read in
	# the log.
	# mergeoptions = --no-commit --no-ff
-------------- next part --------------
# Emacs creates backup files ending with ~ of files managed in a revision
# control system.
*~

# Emacs lock files. Emacs creates such a lock file when you edit a buffer but
# do not save your changes.
.#*
*#*