<< | Page list | >>
In March 2012, the LyX project started using git for version control, rather than subversion.
This page contains information about how to access the new repository and, for developers, about how to use it. Some material about how to use git with LyX and recipes is at the older LyX Git page.
1. Accessing the Repository
2. Cloning the Repository
- Non-developers may clone the main LyX repository via:
git clone git://git.lyx.org/lyx (faster) or via : git clone https://git.lyx.org/repos/lyx.git (slower, but secure)
- Once the repo has been cloned, the current stable branch can be accessed via:
git checkout 2.3.x
- Developers may clone the repository via:
git clone git@git.lyx.org:lyx. This will enable write access as well as read access.
- If you want to clone the stable branch (2.3.x) in a separate folder (let's call it "lyx-2.3.x") than the folder (assume it is "lyx") where you cloned the development branch (master), and you prefer to share the objects already downloaded in the development cloned repo folder, then you can use (from the parent folder) the command:
git clone --reference lyx --shared git@git.lyx.org:lyx -b 2.3.x lyx-2.3.x. This will create a new "lyx-2.3.x" folder with checked out the 2.3.x branch, and a repo sharing the patches database with the development branch already available in the "lyx" folder. The "--shared" option keeps the new cloned repo depending on the one in the original folder, so don't delete it. NOTE: --shared is a possibly dangerous operation; do not use it unless you understand what it does. You can use full clone in case disk space does not matter to you.
2.1 Cloning repository from mirror
Fresh clone size of the current lyx.git repository is close to 1 GB. If you are unlucky and have weak connectivity en route to our primary git server (Oregon, US) getting initial clone might get unbearably long/slow. We offer to speed up the initial clone by putting the complete repo (state in 2024/03) on our ftp server. By carefully selecting mirror, which is geographically closer to you, you might download the major part of the repository significantly faster (e.g. GARR has excellent connectivity to European academic network).
After selecting mirror, you can get the repository from the devel/ directory. The needed file is lyx.tar.xz. You are advised to download the signature as well and check for authenticity of the file.
Put it in some appropriate directory, e.g., $HOME/git/, and unpack it via "tar xJvf lyx.tar.xz". This will create (in our example) $HOME/git/lyx/. The directory will appear to be empty, but the crucial .git/ subdirectory will be there. You can restore the contents of the master branch by running "git checkout ." (note the dot at the end).
After that, you can update the repo to the most recent state via "git pull". On slow connections this might take a bit of time, but a lot less than cloning the whole repository. (From this point, you are connecting directly to primary git site again.) After that you are good to go. The subsequent pulls should be way faster (as there is usually very little to download). You may also want to run "git fetch" to get any new branches (such as new stable branches, such as 2.4.x, which does not exist as of this writing, but will soon).
There is a README.txt file with essentially this information. It can be deleted.
Example session when e.g GARR mirror was selected:
#get git archive
wget https://lyx.mirror.garr.it/devel/lyx.tar.xz
#get signature
wget https://lyx.mirror.garr.it/devel/lyx.tar.xz.sig
#verify signature, check for: Good signature from "LyX Release Manager...
gpg --verify lyx.tar.xz.sig
#unzip into "lyx" directory
tar xvf lyx.tar.xz
#README not needed for you
cd lyx && rm README.txt
#update the repository to the current state
git pull
#get the working directory from the repository
git checkout .
3. Working with the features repository
The features repository contains branches with features that might become reality or not.
- Do not clone the
features repository, but create a remote in your local clone of lyx upstream repository instead:
git remote add features git@git.lyx.org:features.git (read/write access for developers)
git remote add features git://git.lyx.org/features.git (anonymous access for users)
- Use
git fetch features (or git fetch --all) to get updates to the feature branches.
- If you want to work on an existing feature branch, then check it out as a "tracking branch", using:
git checkout --track -b features/thebranch
This will create a branch named "features/thebranch". You can optionally give it a name of your choosing as follows:
git checkout --track -b myname features/thebranch
You can then push to and pull from this branch without having to do anything special. Note: plain push did not work for me (gb), I had to call it like this:
git push features features/thebranch
- To create a branch in this repository, there are two ways to proceed. The first is to create the branch directly on the server, thus:
git push [--set-upstream] features master:newbranch
The --set-upstream option, if provided, will simultaneously check out a tracking branch for your new branch. You can also do this manually, of course:
git checkout --track -b features/newbranch
The other option is to create the branch locally, and then push it to the server:
git push features local_name:remote_name
If you do it that way, remember that your local branch is not yet tracking the remote branch. You have to do that separately:
git branch --set-upstream local_branch features/remote_branch
WARNING: The branches in the features repository might be rebased or rewritten before being merged into master. This means that you should NOT base other work upon a feature branch.
4. Working with the GSoC repository
The gsoc repository contains branches on which our Google Summer of Code students are working. It is used the same was as the features repository. Thus:
- Do not clone the
gsoc repository, but create a remote in your local clone of lyx upstream repository instead:
git remote add gsoc git@git.lyx.org:gsoc.git (read/write access for developers)
git remote add gsoc git:gsoc.git (anonymous access for users)
- Use
git fetch gsoc (or git fetch --all) to get updates to the feature branches.
- If you want to work on an existing feature branch, then check it out as a "tracking branch", using:
git checkout --track -b gsoc/thebranch
This will create a branch named "thebranch". You can optionally give it a name of your choosing as follows:
git checkout --track -b myname gsoc/thebranch
You can then push to and pull from this branch without having to do anything special.
- To create a branch in this repository, there are two ways to proceed. The first is to create the branch directly on the server, thus:
git push [--set-upstream] gsoc master:newbranch
The --set-upstream option, if provided, will simultaneously check out a tracking branch for your new branch. You can also do this manually, of course:
git checkout --track -b gsoc/newbranch
The other option is to create the branch locally, and then push it to the server:
git push gsoc local_name:remote_name
If you do it that way, remember that your local branch is not yet tracking the remote branch. You have to do that separately:
git branch --set-upstream local_branch gsoc/remote_branch
- Mentors have the ability to delete branches, via:
git push --delete gsoc oldbranch
Be careful with this!!
WARNING: The branches in the gsoc repository might be rebased or rewritten before being merged into master. This means that you should NOT base other work upon a feature branch.
5. Suggested git usage for GSoC students
The following steps outline a possible use of git for GSOC students' repositories that is meant to help both students and mentors in keeping track of progress and facilitate code integration.
- Preliminary step: Your mentors should have set up a project branch in the GSOC repository, as detailed above, and given you proper access. If this is not the case, bug them until they do.
- Create your personal branch within the project's repo:
git checkout -b <yourName>
From now on, all your coding should happen within this branch.
- Before starting to work on a feature, create a branch for it in your personal branch
Create a branch for the feature you will be working on. Use a descriptive label for the branch, don't call it "feature1" or "projectStep1". Try to come up with a concise yet meaningful description.
The following git command will create a new branch called "newFeature" directly under the branch called "yourName"
git checkout -b <newFeature> <yourName>
- Work on the feature in that branch
When discussing the problems you are encountering with mentors/devs, point them to the relevant branch you are having troubles with.
They will be able to checkout the branch and review your code in the exact same environment you are working in.
Commit your work frequently!
Do not wait to commit until you have solved all problems and the feature you are implementing works properly. git can only help you organize and integrate your code if you let it know what you are doing. That means committing often. Committing frequently will record the steps you have taken in your work and will help you identify problems down the line (for instance, by using git bisect to pinpoint when a bug was introduced, etcetera).
The rule of thumb is: If it compiles, commit
- When the feature is successfully implemented, merge the "feature branch" back into your personal branch.
When you are satisfied with your results on the feature you have been working on, merge it back into your personal branch:
git checkout <yourName>
git merge --no-ff <newFeature>
- Notice that you can use local branching within your feature branch to work on alternative implementations, if necessary
Repeat the previous process when you are exploring alternative implementations of the feature you are working on. For instance, let's say you have started working on a feature and you are half-way done when you realize that there are a couple of different ways you could proceed. Create a new branch and switch to it with the usual git command:
git checkout -b <firstApproach> <newFeature>.
Work on this approach until you are satisfied. When you want to try a different approach, switch back to the feature branch:
git checkout <newFeature>
then create a new branch for the alternative approach and switch to it:
git checkout -b <secondApproach> <newFeature>.
Merge back into the feature branch the approach you have settled on (say, the second one):
git merge --no-ff <secondApproach>.
6. Personal/private repositories
- Developers may create a private clone of the repository on the server via:
ssh git@git.lyx.org fork lyx developers/LYXUSER/lyx, where of course "LYXUSER" is replaced by the developer's user name.
- Upon creation, this repo will be readable and writeable only by its creator. To allow other users access do:
ssh git@git.lyx.org setperms developers/LYXUSER/lyx. Then enter, e.g.:
READERS LYXUSER otheruser gitweb
WRITERS LYXUSER
[Ctrl-D]
The special user gitweb allows access via http://git.lyx.org/. The special user daemon will allow universal access. Try not to do that for write privileges! The special user @all will allow all fellow developers.
In order to change the description of the repo:
ssh git@git.lyx.org setdesc developers/LYXUSER/lyx
< type your description>
< type Ctrl-D to exit>
7. Use your repo as a remote
Rather than cloning your private repo into a completely separate repository on your machine, you can work with it in the same repository as you main clone of the LyX repo, by setting it up as a remote.
git remote add private git@git.lyx.org:developers/LYXUSER/lyx
Of course, you can replace "private" with whatever you want the name of the remote to be. We'll assume here, however, that it's called "private".
git remote
should now show the new remote. But none of it is actually in our repo yet, so:
git fetch private
- Suppose we now want to start developing a new feature. We will use a "topic branch" connected to our private repo to do this. First, we create the branch:
git checkout -b features/MyFeature
Now we link it to our private upstream repository:
git push --set-upstream private features/MyFeature
This also creates the branch on your upstream repo and pushes the current contents.
- If there is already a branch in your private repo that you'd like to checkout and still have linked to your private repo, then e.g.:
git checkout --track private/bugs/7930
Now by default git pull will pull from your private repo, and git push will push to it.
8. Use your repo through a clone
- You can clone your private repo via:
git clone git@git.lyx.org:developers/LYXUSER/lyx.
- You will want to be able to synchronize your personal repo with the main LyX repo. Thus:
git remote add lyx-git git@git.lyx.org:lyx
will create a new remote tracking the main LyX repo. Then:
git fetch lyx-git
will fetch the main LyX repo and:
git checkout --track lyx-git/master lyx/trunk
will set up a branch, lyx/trunk, that tracks it. So now you can do things like:
git checkout master
git rebase lyx/trunk
to pull upstream changes into your local master branch. (By rebasing, we avoid a pointless merge commit.) Note that you will need to pull in the new changes from lyx/trunk before you rebase.
- Similarly, you can set up a branch for, uhh, branch:
git checkout --track -b lyx-git/2.3.x lyx/branch
- If you want to work on a bug or feature in your repo, first create a branch for it. We'll base it on the main trunk:
git checkout lyx/trunk
and create the new branch:
git checkout -b features/MyFeature
and then link it to our upstream developer repo, NOT the main LyX repo:
git push --set-upstream origin features/MyFeature
Now when you do:
git push
from within your repo, it pushes to a branch in your developer repo. Obviously, you can use whatever names you want for your branches, but using "features/*", and "bugs/*", and the like helps keep things organized.
- To keep the branch up to date with changes in the main repo, we need to do:
git checkout lyx/trunk
git pull --rebase
git checkout features/MyFeature
git rebase lyx/trunk
If there are any conflicts, they will need to be fixed and committed.
FIXME Add a bit about how to do that.?
- Suppose you are now happy with your new feature. So we're ready to get it into the main repo. There are a few ways to do this.
- Way 1: Merge the feature branch into
lyx/trunk and push it.
First, we make sure our feature branch is up to date:
git checkout features/MyFeature
git rebase lyx/trunk
This avoids a pointless merge commit later.
git checkout lyx/trunk
git merge features/MyFeature
It's worth having a look at the history now to make sure it's as you want:
gitk
If so, we're ready to push. But let's make sure first that this will do what we want:
git push -n
If that's OK, then go ahead:
git push
- Way 2: Push the feature branch directly:
git checkout features/MyFeature
git rebase lyx/trunk
This avoids a pointless merge commit. Let's check the history:
gitk
Now we're ready to push:
git push -n lyx-git features/MyFeature:master
If that looks OK, then go ahead:
git push lyx-git features/MyFeature:master
- To link to git commits in TRAC, use: [7d200f30/lyxgit].
9. Recovering apparently lost stuff
- git tracks copies of whatever you commit into its reflog (just try "git reflog"); often if you messed up with your commits while squashing or resetting or others, you can still recover your previously committed changes from the reflog
- "safety hints" from Cyrille: IMHO git works well if
- (1) You are very careful and RTFM closely before using "reset", "rebase".
- (2) If any option has "--hard" and read up on the same topic on other sources, or ask someone, before proceeding.
- (3) Be aware that "git stash" is local and does not get pushed. No use stashing work in progress if you're about to go on a business trip with no access to the machine with the stashed stuff
10. Categories
Category: Development, LyXGit
