Git Usage Windows: Difference between revisions
>WiSo No edit summary |
RogueScholar (talk | contribs) (Begin article content refresh and expansion) |
||
(13 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
{{Main|Git usage}} | |||
{{See also|Windows development}} | |||
Kodi now uses [[w:Git|Git]] as its [[w:Version control|version control system]], or more simply, the method by which changes to the codebase are recorded. It offers many advantages to the Kodi development team, among them the ability for developers to make contributions from a wide variety of operating systems, including any version of the Windows operating system currently supported by Microsoft. | |||
=== | == Working with the Kodi source code == | ||
=== Clone the main repository === | |||
< | {{Notice|As of September 2021, the main Kodi source code repository requires >730 MiB of available storage on your local system, and is constantly growing in size. Be sure you are willing to allocate at least that much disk space before attempting to clone it.|Disk space requirements}} | ||
The main code repository is hosted at [https://github.com/xbmc/xbmc GitHub] and available in its entirety for anyone to examine without registering for an account. In this guide we're demonstrating a few common tasks when working with the Kodi source code, using the official [https://git-scm.com/download/win Git for Windows] implementation to add Git functionality to Windows and [https://tortoisegit.org/download/ TortoiseGit] as the "frontend" for the examples showing a GUI interface instead of the command line. | |||
</ | |||
==== Using the terminal ==== | |||
To download a copy of the main repository to your Downloads folder with read-only access and make that your working directory, you can use either the traditional [https://www.lifewire.com/how-to-open-command-prompt-2618089 Command shell] or its newer replacement, [https://docs.microsoft.com/en-us/powershell/scripting/windows-powershell/starting-windows-powershell PowerShell]; both are included with every Windows installation by default and offer identical performance when using Git for Windows, the choice is dictated solely by what you're most familiar with. | |||
* Command Prompt: | |||
<syntaxhighlight lang="doscon" highlight="1,3,13,15"> | |||
C:\> cd %USERPROFILE%\Downloads | |||
C:\Users\Username\Downloads\> git clone https://github.com/xbmc/xbmc.git | |||
Cloning into 'xbmc'... | |||
remote: Enumerating objects: 580599, done. | |||
remote: Counting objects: 100% (1932/1932), done. | |||
remote: Compressing objects: 100% (455/455), done. | |||
remote: Total 580599 (delta 987), reused 1763 (delta 910), pack-reused 578667 | |||
Receiving objects: 100% (580599/580599), 733.52 MiB | 4.54 MiB/s, done. | |||
Resolving deltas: 100% (431423/431423), done. | |||
Updating files: 100% (9234/9234), done. | |||
C:\Users\Username\Downloads\> cd xbmc | |||
C:\Users\Username\Downloads\xbmc> | |||
</syntaxhighlight> | |||
* Powershell: | |||
<syntaxhighlight lang="pwsh-session" highlight="1,7,16-17"> | |||
PS C:\> Set-Location -Path "$Env:UserProfile\Downloads" -PassThru | |||
Path | |||
---- | |||
C:\Users\Username\Downloads | |||
PS C:\Users\Username\Downloads\> git clone https://github.com/xbmc/xbmc.git | |||
Cloning into 'xbmc'... | |||
remote: Enumerating objects: 580599, done. | |||
remote: Counting objects: 100% (1932/1932), done. | |||
remote: Compressing objects: 100% (455/455), done. | |||
remote: Total 580599 (delta 987), reused 1763 (delta 910), pack-reused 578667 | |||
Receiving objects: 100% (580599/580599), 733.52 MiB | 4.54 MiB/s, done. | |||
Resolving deltas: 100% (431423/431423), done. | |||
Updating files: 100% (9234/9234), done. | |||
PS C:\Users\Username\Downloads\> Set-Location -Path ".\xbmc" | |||
PS C:\Users\Username\Downloads\xbmc> | |||
</syntaxhighlight> | |||
For read/write access (Devs only) via ssh keys (your account needs to be added to the xbmc project on github) | For read/write access (Devs only) via ssh keys (your account needs to be added to the xbmc project on github) | ||
< | <syntaxhighlight lang="bash" enclose="div"> | ||
$ git clone [email protected]:xbmc/xbmc.git | $ git clone [email protected]:xbmc/xbmc.git | ||
</ | </syntaxhighlight> | ||
For read/write access (Devs only) via user/pass (yourname needs to be added to the xbmc project on github) | For read/write access (Devs only) via user/pass (yourname needs to be added to the xbmc project on github) | ||
< | <syntaxhighlight lang="bash" enclose="div"> | ||
$ git https://[email protected]/xbmc/xbmc.git | $ git https://[email protected]/xbmc/xbmc.git | ||
</ | </syntaxhighlight> | ||
==== TortoiseGit ==== | |||
* right click in your directory tree | * right click in your directory tree | ||
* choose "Git Clone" | * choose "Git Clone" | ||
*: [[ | *: [[File:Tortoise_clone.png]] | ||
* replace yourname with your github user account | * replace yourname with your github user account | ||
* when asking for the password type in your github password. | * when asking for the password type in your github password. | ||
* you can also use ssh keys for authentication. | * you can also use ssh keys for authentication. | ||
== Fetch old branches and extra history == | === Fetch old branches and extra history === | ||
'''The following is ONLY useful for developers who wish to see extended | '''The following is ONLY useful for developers who wish to see extended Kodi history. Everyone else should stop here.''' | ||
Run this command from your tree. It requires git 1.6.5 or higher: | Run this command from your tree. It requires git 1.6.5 or higher: | ||
< | <syntaxhighlight lang="bash" enclose="div"> | ||
$ git fetch origin refs/old/heads/*:refs/remotes/svn-migration/* refs/replace/*:refs/replace/* | $ git fetch origin refs/old/heads/*:refs/remotes/svn-migration/* refs/replace/*:refs/replace/* | ||
</ | </syntaxhighlight> | ||
== Platform Settings == | (Is this possible in gui too?) | ||
=== Case Insensitive File Systems=== | |||
=== 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 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: | ||
< | <syntaxhighlight lang="bash" enclose="div">$ git config --list</syntaxhighlight> | ||
if not set: | if not set: | ||
< | <syntaxhighlight lang="bash" enclose="div">$ git config --global core.ignorecase true</syntaxhighlight> | ||
(true is the default value for msysgit) | |||
==== Line Endings ==== | |||
Windows users MUST use the git autocrlf feature. This is set by default by tortoise if you don't change it during the installation process. If it's not set, you can do so manually: | |||
< | <syntaxhighlight lang="bash" enclose="div">$ git config --system core.autocrlf true</syntaxhighlight> | ||
or via the gui: | |||
* right click on you cloned xbmc directory | |||
* TortoiseGit -> Settings | |||
* navigate to Git -> Config | |||
* check that AutoClrf is marked | |||
while you are there you should enter your name and email in the fields above. Otherwise you'll be asked during the first push. | |||
== Updating == | === Updating === | ||
When updating from the main git repo (by default git will call this 'origin'), you should always rebase on top of your history, unless you know what you're doing. | When updating from the main git repo (by default git will call this 'origin'), you should always rebase on top of your history, unless you know what you're doing. | ||
<syntaxhighlight lang="bash" enclose="div">git pull --rebase</syntaxhighlight> | |||
A safe bet is to set this to be done automatically. | |||
<syntaxhighlight lang="bash" enclose="div">$ git config branch.master.rebase true</syntaxhighlight> | |||
with the gui: | |||
* right click on the xbmc repo | |||
* choose '''Git Sync...''' | |||
* go to the option field in the bottom left | |||
* press the down arrow and choose '''Fetch&Rebase''' | |||
* press '''Fetch&Rebase''' | |||
* press '''rebase (fast fwd)''' in the newly appearing dialog | |||
*: [[File:Fetch_and_Rebase.png]] | |||
=== Committing === | |||
commit your local work to your local repository: | |||
== Pushing == | * right click on the xbmc repo | ||
Please use < | * choose '''Git Commit -> "master"... ''' | ||
* type in a commit message | |||
* choose the files to commit | |||
* press ok | |||
=== Pushing === | |||
Pushes your work from the local repository to the xbmc main repository at github. | |||
Please use <syntaxhighlight lang="bash" enclose="div">git log</syntaxhighlight> to look at the log before committing. 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. | '''Never EVER force a push (non-fast-forward commit) to mainline. Ever. Doing so will result in your push privileges being revoked. | ||
* right click on the xbmc repo | |||
* TortoiseGit -> Push... | |||
* press Ok | |||
Attention: this will push all your local committed changes to the xbmc main repo. I dunno if you can only choose certain commits via the gui. | |||
[[Category:Development]] |
Latest revision as of 08:36, 13 September 2021
Kodi now uses Git as its version control system, or more simply, the method by which changes to the codebase are recorded. It offers many advantages to the Kodi development team, among them the ability for developers to make contributions from a wide variety of operating systems, including any version of the Windows operating system currently supported by Microsoft.
Working with the Kodi source code
Clone the main repository
Disk space requirements: As of September 2021, the main Kodi source code repository requires >730 MiB of available storage on your local system, and is constantly growing in size. Be sure you are willing to allocate at least that much disk space before attempting to clone it. |
The main code repository is hosted at GitHub and available in its entirety for anyone to examine without registering for an account. In this guide we're demonstrating a few common tasks when working with the Kodi source code, using the official Git for Windows implementation to add Git functionality to Windows and TortoiseGit as the "frontend" for the examples showing a GUI interface instead of the command line.
Using the terminal
To download a copy of the main repository to your Downloads folder with read-only access and make that your working directory, you can use either the traditional Command shell or its newer replacement, PowerShell; both are included with every Windows installation by default and offer identical performance when using Git for Windows, the choice is dictated solely by what you're most familiar with.
- Command Prompt:
C:\> cd %USERPROFILE%\Downloads C:\Users\Username\Downloads\> git clone https://github.com/xbmc/xbmc.git Cloning into 'xbmc'... remote: Enumerating objects: 580599, done. remote: Counting objects: 100% (1932/1932), done. remote: Compressing objects: 100% (455/455), done. remote: Total 580599 (delta 987), reused 1763 (delta 910), pack-reused 578667 Receiving objects: 100% (580599/580599), 733.52 MiB | 4.54 MiB/s, done. Resolving deltas: 100% (431423/431423), done. Updating files: 100% (9234/9234), done. C:\Users\Username\Downloads\> cd xbmc C:\Users\Username\Downloads\xbmc>
- Powershell:
PS C:\> Set-Location -Path "$Env:UserProfile\Downloads" -PassThru Path ---- C:\Users\Username\Downloads PS C:\Users\Username\Downloads\> git clone https://github.com/xbmc/xbmc.git Cloning into 'xbmc'... remote: Enumerating objects: 580599, done. remote: Counting objects: 100% (1932/1932), done. remote: Compressing objects: 100% (455/455), done. remote: Total 580599 (delta 987), reused 1763 (delta 910), pack-reused 578667 Receiving objects: 100% (580599/580599), 733.52 MiB | 4.54 MiB/s, done. Resolving deltas: 100% (431423/431423), done. Updating files: 100% (9234/9234), done. PS C:\Users\Username\Downloads\> Set-Location -Path ".\xbmc" PS C:\Users\Username\Downloads\xbmc>
For read/write access (Devs only) via ssh keys (your account needs to be added to the xbmc project on github)
$ git clone [email protected]:xbmc/xbmc.git
For read/write access (Devs only) via user/pass (yourname needs to be added to the xbmc project on github)
$ git https://[email protected]/xbmc/xbmc.git
TortoiseGit
- right click in your directory tree
- choose "Git Clone"
- replace yourname with your github user account
- when asking for the password type in your github password.
- you can also use ssh keys for authentication.
Fetch old branches and extra history
The following is ONLY useful for developers who wish to see extended Kodi 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/*
(Is this possible in gui too?)
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
(true is the default value for msysgit)
Line Endings
Windows users MUST use the git autocrlf feature. This is set by default by tortoise if you don't change it during the installation process. If it's not set, you can do so manually:
$ git config --system core.autocrlf true
or via the gui:
- right click on you cloned xbmc directory
- TortoiseGit -> Settings
- navigate to Git -> Config
- check that AutoClrf is marked
while you are there you should enter your name and email in the fields above. Otherwise you'll be asked during the first push.
Updating
When updating from the main git repo (by default git will call this 'origin'), you should always rebase on top of your history, unless you know what you're doing.
git pull --rebase
A safe bet is to set this to be done automatically.
$ git config branch.master.rebase true
with the gui:
- right click on the xbmc repo
- choose Git Sync...
- go to the option field in the bottom left
- press the down arrow and choose Fetch&Rebase
- press Fetch&Rebase
- press rebase (fast fwd) in the newly appearing dialog
Committing
commit your local work to your local repository:
- right click on the xbmc repo
- choose Git Commit -> "master"...
- type in a commit message
- choose the files to commit
- press ok
Pushing
Pushes your work from the local repository to the xbmc main repository at github.
Please use
git log
to look at the log before committing. 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.
- right click on the xbmc repo
- TortoiseGit -> Push...
- press Ok
Attention: this will push all your local committed changes to the xbmc main repo. I dunno if you can only choose certain commits via the gui.