LyX wiki | Devel / Git

Using your own git branch to work with lyx.

Table of contents

Preliminary
Using git-svn
1. 2.1 Setup branch with svn-git
2. 2.2 Working with one branch
3. 2.3 Working with more branches
4. 2.4 Other git examples
5. 2.5 Contributing back
6. 2.6 Conclusion
Using the Git mirror repository

Preliminary

There are various reason why one start to use git. Firstly you don't need commit access to svn to maintain your own diverged tree from the official one, secondly git itself is more powerfull to maintain more branches - including merging capabilities, visualizing, hardlinking etc.

(Edit Section ↓)

Using git-svn

To start your work you will need installed subversion for fetching, git and git-svn (git-svn script can be part of your git package by default, for its working you will need subversion perl support enabled and also libwww-perl package).

(Edit Section ↓)

Setup branch with svn-git

For some operations your identity will be needed:

git config --global user.name "Your Name Comes Here"
git config --global user.email you@yourdomain.example.com

Now choose what part do you want to import. This will be usually trunk, but maybe you want the branches (look on special switches for init to specify this) or the whole repo.

 
#Choose the directory for your branch, eg:
cd ~/git/lyx/trunk

#prepare directory
git-svn init svn://svn.lyx.org/lyx/lyx-devel/trunk

#fetching from revision 20100
git-svn fetch -r 20100

#if you have write access to svn, you probably want to use svn dcommit for commit, so you have to setup this way:
#git-svn clone svn+ssh://developer_name@svn.lyx.org/lyx/lyx-devel/trunk -r REVISION_NUMBER_TO_CLONE

#updating to the latest revision
git-svn rebase

For fetching the whole history (be prepared that this operation takes lot of time(hours) and network bandwidth as all commits will be fetched):

 
cd ~/git/lyx
git-svn clone svn://svn.lyx.org/lyx/lyx-devel/trunk

Now you can denote your own branch if you want:

git-checkout -b branch_name

(Edit Section ↓)

Working with one branch

Usually the cycle will look like this:

#editing changes
vi blabla.cpp

#commiting changes
#now your changes will be the in the last-log
git commit -a

#updating from svn (something like "svn up")
#after this your changes will be again in the last log as before updating, as they are reverted
#and after updating again merged. remember to commit before updating.
git-svn rebase

#you can do this regularly, because if there is some merge conflict you can take the whole operation back by:
git rebase --abort

#or you can edit the conflicts now
#to see where the conflict are:
git diff
#repair it
vi conflict.file
#tell git conflict is resolved
git update-index conflict.file
#continue with rest of patches
git rebase --continue


#if you don't like commiting before updating, you can study these commands:
git-add . ; git-commit -m "temporary commit"
git-svn rebase
git-reset --mixed HEAD^

#to throw local changes away from branch:
git checkout -f

#to restore unintentionally removed file: 
git checkout deleted.file

#reverting file two commits back:
git checkout branchname~2 file

(Edit Section ↓)

Working with more branches

Imagine you denoted your branch at the beginning 'newfeature'. Now you would like to make some comparisons between current trunk and your locally commited code without changing anythning in newfeature. One possibility is to coin new branch, say trunk, and use this branch simultaneously.

#display available branches (the current has asterisk)
git branch

#now we will go 10 patches back (ie somewhere before you started work on your own)
git checkout master~10

#now you can look, that you moved into some (probably) unnamed branch, which is trunk before you started work or even denoting it by newfeature.
git branch

#you can name this branch trunk
git checkout -b trunk

#and make the trunk up to date;look on 'git log' and 'git branch' after 
git-svn rebase

#now you can switch back to your devel branch
git checkout newfeature

#you can see the difference between trunk and newfeature; git-svn is still usable here in newfeature...
git diff trunk..newfeature

#switch from current branch with local changes to another_branch with 3-way merge:
git checkout -m another_branch

By checkout -b you can create many branches and merge them back (possiby more branches in one merge etc.) - look into manual. To have graphical view of branching and history you can use simpler gitk or more sophisticated qgit.

As branches are very cheap their number increase, and most of them is not used anymore. You can either delete the branch by

git branch -d mybranch

or tag it before delete

git tag tagofmybranch

to make easy handle for potential checkout or diffs in the future (commits remain in repository, although the branch wont be visible now).

(Edit Section ↓)

Other git examples

#See all commits touching particular file (-p for printing diffs too)
git whatchanged file

#undo last commit or merge
git reset HEAD^

#see symmetric differences (in commits) between two branches
git log trunk...mybranch

#see commits which touched particular file
git log path(s)-or-file(s)

#the same but only in last two weeks
git log --since="2 weeks ago" -- files


#Applying patch(commit) from a different branch
git-cherry-pick -n <commit_number>
or complicated way
git diff commit..commit^|git apply
or revert another commit
git show commit|git apply --reverse

#Searching in the commit history
#you can obtain the list of commits where STRING were in changed part (ie +/-)
git log --pretty=oneline  -S'STRING'
#or you can use classical blame, but note that git blame is much more sophisticated. He is able to detect movement of lines between parts of file 
#or even files when this  movement happens during one commit. So
git blame file
#is able to step origin of lines even through the shifts like the big renaming calamity of smallfile.C -> SmallFile.cpp etc.
#You can consult blame parameters to refine these shifts detections.


#Searching the bug via bisect.
#Usual case you have some error in the current tree (HEAD).
#This will also git-reset the old good/bad intervals
git bisect start
#start defining new interval
git bisect bad HEAD
#now go back in history to get some revision which is ok. this may be iterated. eg:
git checkout HEAD^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
#suppose you are now in revision which was ok
git bisect good HEAD
# that created new border of good-bad interval and switch you to the half of the good-bad interval.
# Simply reiterate with the proper good/bad flags till the end, where git give you the log of the problematic commit.


#Postponing your changes for a while, getting back to fresh tree and then getting back tree with your changes
git stash              ##saving it, now you are on clean tree
git stash show -p      ##showing the diff in stash against the current tree
git stash apply        ##get things fromstash back to the tree
git stash clear


#Repair last commit
git commit --amend                  #Only change commit message
git add file; git commit --amend    #Repair some change in file

You can create .gitignore file in the top level of branch with list of ignored (see git status) files, you can also use wildcards.

If you like colors you can configure git for them:

git config --global color.diff auto
git config --global color.status auto
git config --global color.branch auto

(Edit Section ↓)

Contributing back

To get the patch set, say of three last commits:

git-format-patch -3 --stdout

If you have also write access to svn you can directly use git-svn dcommit.

(Edit Section ↓)

Conclusion

This is just shortcut for quick start with using git. git itself is much more powerful tool, so you should look on other links for svn+git:

and the many guides to the git itself as it is possible you want more branches, centralized repo for merging them together etc.

(Edit Section ↓)

Using the Git mirror repository

Instead of working with the lyx-devel subversion repository directly (as shown above), you can simply use the unofficial Git mirror at repo.or.cz. In this case you can use the normal Git workflow and commands, such as "git pull", "git fetch" and "git rebase".

To clone that repository (currently ~160 Mb), use:

git clone git://repo.or.cz/lyx.git

Then proceed using your favorite Git tutorial, but note that you cannot push into the mirror repository.

Category: Development, Tips