Git usage: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
>Theuni
No edit summary
 
(36 intermediate revisions by 13 users not shown)
Line 1: Line 1:
There's now a git repository available for XBMC. This page is intended as an instructional page showing how to clone the XBMC git repository along with notes on how to start fetching newer revisions through XBMC's svn repository.
{{mininav|[[Development]]}}


Eventually, the git repository will be the main repository for development. Currently, the git repository is synced with changes made to the svn repository every four minutes.
==Git windows guide==
The guide for Windows users is located here: [[Git Usage Windows]]
== Clone the XBMC main repository ==
XBMC now uses git as its Software Configuration Management (SCM) framework. The main repository is located at [https://github.com/xbmc/xbmc github]


First thing, clone the repo.
For read only access
<source lang="bash">
<source lang="bash">
$ git clone git://xbmc.git.sourceforge.net/gitroot/xbmc/xbmc
  $ git clone git://github.com/xbmc/xbmc.git
</source>
</source>


After cloning the repo, you may notice a lot of branches that are no longer in the svn repo, and also branches and tags which are appended with '@' followed by some number. These are all the branches and tags git-svn found when doing the initial import from the svn repo. If you do not intend to track svn, you may proceed to delete these stale branches, otherwise, you should keep them so that the time to do an initial fetch with git-svn doesn't take days (that's right, DAYS).
If you are a developer, clone the repository.
 
== Sync with SVN For dcommit ==
'''The following is ONLY useful if you have svn commit access. Everyone else should stop here.'''
<source lang="bash">
<source lang="bash">
$ cd xbmc
  $ git clone [email protected]:xbmc/xbmc.git
$ git svn init --stdlayout --prefix=origin/ https://xbmc.svn.sourceforge.net/svnroot/xbmc
$ git config svn-remote.svn.tags tags/*:refs/tags/*
</source>
</source>
NOTE: Don't forget the trailing '/' for the prefix option in 'git svn init'.


You will save yourself a headache by removing the git url so that you can't fetch it by accident:
== Fetch old branches and extra history ==
'''The following is ONLY useful for developers who wish to see extended XBMC history. Everyone else should stop here.'''
Run this command from your tree. It requires git 1.6.5 or higher:
<source lang="bash">
<source lang="bash">
$ git config --unset remote.origin.url
$ git fetch origin refs/old/heads/*:refs/remotes/svn-migration/* refs/replace/*:refs/replace/*
</source>
</source>


Now do the fetch. If you left all branches and tags that were cloned alone, this should take roughly half an hour, as opposed to several days.
== Platform Settings ==
<source lang="bash">
=== Case Insensitive File Systems ===
$ git svn fetch
Git wants to run under a case sensitive file system but under OSX and Windows, the file system might be case insensitive. Make sure that core.ignorecase is properly set. Check with:
</source>
<source lang="bash">$ git config --list</source>
It is possible to fetch history only from a certain SVN revision (1234 in this example) with the following:
if not set:
<source lang="bash">
<source lang="bash">$ git config --global core.ignorecase true</source>
$ git svn fetch -r 1234
 
</source>
=== Line Endings ===
 
Windows users MUST use the git autocrlf feature. This is set by default by tortoise. If it's not set, you can do so manually:
<source lang="bash">$ git config --system core.autocrlf true</source>
 
Linux and OSX users should set autocrlf to 'input'
<source lang="bash">$ git config --global core.autocrlf input</source>
 
== Updating ==
 
When updating from the main git repository (by default git will call this 'origin'), you should always rebase on top of your history, unless you know what you're doing.


Once finished, you should be at the master branch which tracks 'trunk' from svn. You can check by doing a dry-run of a check in to svn, via the dcommit command from git-svn.
Always use <source lang="bash">git pull --rebase</source>
<source lang="bash">
$ git svn rebase
$ git svn dcommit -n
Committing to https://xbmc.svn.sourceforge.net/svnroot/xbmc/trunk ...
</source>
NOTE: Don't forget the '-n' option to perform a dry-run, otherwise it will try to perform an actual check in.


That's basically all there is to it. To keep following svn for new revisions, it's simply fetching new changes again and rebasing.
A safe bet is to set this to be done automatically.
<source lang="bash">
<source lang="bash">$ git config branch.master.rebase true</source>
$ git svn fetch && git svn rebase
== Pushing ==
</source>
Please use <source lang="bash">git log</source> to look at the log before pushing. If there are merge commits that you don't understand, please ask for help before pushing.


== Other Repos ==
'''Never EVER force a push (non-fast-forward commit) to mainline. Ever. Doing so will result in your push privileges being revoked.
There are also other repos that are kept in sync with new changes from the svn repository.
== Merging ==


A repository is available at github.
Always use the --log option to add a description of what commits are being merged. You can (and should) set this as a default:
<pre>
<source lang="bash">$ git config merge.log true</source>
git://github.com/ceros/xbmc.git
</pre>


== Git (OSX/Windows) ==
== Advanced ==
=== Case Insensitive File Systems===
=== Maintaining a rebased version of a merge branch ===
Git wants to run under a case sensitive file system but under OSX and Windows, the file system might be case insensitive. Make sure that core.ignorecase is properly set. Check with:
A long-lived feature branch involving a bunch of developers at some point needs merging to mainline.  During the review stage, this typically involves someone taking the time to rebase the feature branch on mainline so that the changes are easier to review for others, with a pull request being made.  Review will inevitably result in fix commits being required, and where many developers are involved this can be messy if constantly rebased (as devs are working against a moving target). An alternative is to have 2 branches: The first rebased branch changes to the development branch with fixup commits being applied. A second branch is then created which is identical to the first, just rebased down. In order to maintain this arrangement, you need to be able to apply the top N commits from the development branch onto the rebased branch to ensure it's kept up to date.  This can be done as follows:
  "git-config --list"
<source lang="bash">
if not set:
$ git checkout feature_branch
  "git-config --global core.ignorecase true"
$ git checkout -b feature_rebase
$ # ... do rebase ...
$ git diff feature_branch                                    # ensure your rebase hasn't dropped something.
$ git checkout feature_branch
$ git tag -f feature_last_rebase                              # so you know when you last rebased.
$ # ... more commits on top of feature_branch ...
$ git checkout feature_rebase
$ git checkout -b tmp                                        # create a temporary branch
$ git branch -f feature_rebase feature_branch                # move feature_rebase to the HEAD of feature_branch
$ git rebase --onto tmp feature_last_rebase feature_rebase    # rebase changes from the last rebase on top of feature_branch
$ git diff feature_branch                                    # ensure your rebased branch contains all the commits you want
$ git branch -d tmp
$ # ... do rebase ...
</source>
You then just rinse/repeat until all issues are ironed out.  feature_rebase is then what is pulled into master nice and cleanly.
[[Category:Development]]
[[Category:Manual]]
{{nobots}}

Latest revision as of 22:00, 17 November 2014

Home icon grey.png   ▶ Development ▶ Git usage

Git windows guide

The guide for Windows users is located here: Git Usage Windows

Clone the XBMC main repository

XBMC now uses git as its Software Configuration Management (SCM) framework. The main repository is located at github

For read only access

  $ git clone git://github.com/xbmc/xbmc.git

If you are a developer, clone the repository.

  $ git clone [email protected]:xbmc/xbmc.git

Fetch old branches and extra history

The following is ONLY useful for developers who wish to see extended XBMC history. Everyone else should stop here. Run this command from your tree. It requires git 1.6.5 or higher:

$ git fetch origin refs/old/heads/*:refs/remotes/svn-migration/* refs/replace/*:refs/replace/*

Platform Settings

Case Insensitive File Systems

Git wants to run under a case sensitive file system but under OSX and Windows, the file system might be case insensitive. Make sure that core.ignorecase is properly set. Check with:

$ git config --list

if not set:

$ git config --global core.ignorecase true

Line Endings

Windows users MUST use the git autocrlf feature. This is set by default by tortoise. If it's not set, you can do so manually:

$ git config --system core.autocrlf true

Linux and OSX users should set autocrlf to 'input'

$ git config --global core.autocrlf input

Updating

When updating from the main git repository (by default git will call this 'origin'), you should always rebase on top of your history, unless you know what you're doing.

Always use

git pull --rebase

A safe bet is to set this to be done automatically.

$ git config branch.master.rebase true

Pushing

Please use

git log

to look at the log before pushing. If there are merge commits that you don't understand, please ask for help before pushing.

Never EVER force a push (non-fast-forward commit) to mainline. Ever. Doing so will result in your push privileges being revoked.

Merging

Always use the --log option to add a description of what commits are being merged. You can (and should) set this as a default:

$ git config merge.log true

Advanced

Maintaining a rebased version of a merge branch

A long-lived feature branch involving a bunch of developers at some point needs merging to mainline. During the review stage, this typically involves someone taking the time to rebase the feature branch on mainline so that the changes are easier to review for others, with a pull request being made. Review will inevitably result in fix commits being required, and where many developers are involved this can be messy if constantly rebased (as devs are working against a moving target). An alternative is to have 2 branches: The first rebased branch changes to the development branch with fixup commits being applied. A second branch is then created which is identical to the first, just rebased down. In order to maintain this arrangement, you need to be able to apply the top N commits from the development branch onto the rebased branch to ensure it's kept up to date. This can be done as follows:

$ git checkout feature_branch
$ git checkout -b feature_rebase
$ # ... do rebase ...
$ git diff feature_branch                                     # ensure your rebase hasn't dropped something.
$ git checkout feature_branch
$ git tag -f feature_last_rebase                              # so you know when you last rebased.
$ # ... more commits on top of feature_branch ...
$ git checkout feature_rebase
$ git checkout -b tmp                                         # create a temporary branch
$ git branch -f feature_rebase feature_branch                 # move feature_rebase to the HEAD of feature_branch
$ git rebase --onto tmp feature_last_rebase feature_rebase    # rebase changes from the last rebase on top of feature_branch
$ git diff feature_branch                                     # ensure your rebased branch contains all the commits you want
$ git branch -d tmp
$ # ... do rebase ...

You then just rinse/repeat until all issues are ironed out. feature_rebase is then what is pulled into master nice and cleanly.