Difference between revisions of "WesnothRepository"

From The Battle for Wesnoth Wiki
m (Lead section; Browse the code: Copy-editing.)
(Download: Copy-editing; expand first FAQ answer.)
Line 23: Line 23:
 
==  Download  ==
 
==  Download  ==
  
To '''''clone''''' a copy of the repository into a directory called ''wesnoth'',
+
To '''''clone''''' a copy of the repository into a directory called "''wesnoth''",
  
  git clone <nowiki>https://github.com/wesnoth/wesnoth.git</nowiki> wesnoth
+
  git clone "<nowiki>https://github.com/wesnoth/wesnoth.git</nowiki>" wesnoth
  
 
{{SideBox|style=font-size:.75em;line-height:1.6|There are other '''<dfn>transport protocols</dfn>''', in addition to '''Hypertext Transfer Protocol Secure (HTTPS)''', over which one can clone a Git repository from GitHub, including:
 
{{SideBox|style=font-size:.75em;line-height:1.6|There are other '''<dfn>transport protocols</dfn>''', in addition to '''Hypertext Transfer Protocol Secure (HTTPS)''', over which one can clone a Git repository from GitHub, including:
Line 36: Line 36:
 
=== FAQ ===
 
=== FAQ ===
  
'''Q: The repository is ~3GB! My internet connection is not stable enough to reliably download in one sitting. What to do?'''
+
'''Q: The repository is ~3 gigabytes, and my Internet connection is not stable enough to reliably download it. What should I do?'''
  
 
'''A:''' https://stackoverflow.com/questions/9268378/how-do-i-clone-a-large-git-repository-on-an-unreliable-connection
 
'''A:''' https://stackoverflow.com/questions/9268378/how-do-i-clone-a-large-git-repository-on-an-unreliable-connection
  
# Use any download manager to download the directory https://github.com/wesnoth/wesnoth.git, in one or multiple sessions
+
# Use a download manager to download the directory "https://github.com/wesnoth/wesnoth.git", in one or more sessions.
# Rename the folder wesnoth.git to .git
+
# Put this "''wesnoth.git''" directory, which is the internals of the <cite>Wesnoth</cite> repository, in a new, empty directory.
# Finally execute commands:
+
# Rename the "''wesnoth.git''" directory to "''.git''".
 +
# Finally, run these commands in the directory that contains the "''.git''" directory:
  
  git remote add remote <nowiki>https://github.com/wesnoth/wesnoth.git</nowiki>
+
'''$''' git remote add remote "<nowiki>https://github.com/wesnoth/wesnoth.git</nowiki>"
  git reset --hard HEAD
+
'''$''' git reset --hard HEAD
  
This links the repo to the upstream repo, and builds your local copy of wesnoth from the info in the repo file.
+
The first command links your local repository to the upstream repository; the second <dfn>checks out</dfn> a <dfn>working tree</dfn> (i.e., copies the files out of the "''.git''" directory into a form that you can use).
  
  
'''Q: I don't want any alternate versions or repository history. How do I avoid downloading that?'''
+
'''Q: I don't want any alternate branches or repository history. How could I avoid downloading that?'''
  
'''A:''' This simply requires a more elaborate command. For example to only download the last revision of 1.12 branch, and store in a folder "wesnoth-1.12-single-branch-test",
+
'''A:''' This simply requires a more elaborate command. For example, to only download the last revision of the 1.12 branch, and store it in a directory named "''wesnoth-1.12-single-branch-test''":
  
  git clone -b 1.12 --depth 1 --single-branch --no-hardlinks <nowiki>https://github.com/wesnoth/wesnoth.git</nowiki> wesnoth-1.12-single-branch-test
+
'''$''' git clone --branch 1.12 --single-branch --depth 1 "<nowiki>https://github.com/wesnoth/wesnoth.git</nowiki>" wesnoth-1.12-single-branch-test
  
 +
Example results:
  
Sample results:
+
'''$''' git clone --branch 1.12 --single-branch --depth 1 "<nowiki>https://github.com/wesnoth/wesnoth.git</nowiki>" wesnoth-1.12-single-branch-test
 +
Cloning into 'wesnoth-1.12-single-branch-test'...
 +
remote: Counting objects: 18725, done.
 +
remote: Compressing objects: 100% (17541/17541), done.
 +
remote: Total 18725 (delta 1571), reused 7397 (delta 1004)
 +
Receiving objects: 100% (18725/18725), 376.17 MiB | 171.00 KiB/s, done.
 +
Resolving deltas: 100% (1571/1571), done.
 +
Checking connectivity... done.
 +
Checking out files: 100% (18593/18593), done.
 +
'''$''' du -sh wesnoth-1.12-single-branch-test ''# "du" means "disk usage".''
 +
1.1G wesnoth-1.12-single-branch-test
  
  $ git clone -b 1.12 --depth 1 --single-branch --no-hardlinks <nowiki>https://github.com/wesnoth/wesnoth.git</nowiki> wesnoth-1.12-single-branch-test
+
However, for development and testing, it is often better to have some of the repository history, so that you can quickly check out older versions of the repository to pin down a bug.
  Cloning into 'wesnoth-1.12-single-branch-test'...
 
  remote: Counting objects: 18725, done.
 
  remote: Compressing objects: 100% (17541/17541), done.
 
  remote: Total 18725 (delta 1571), reused 7397 (delta 1004)
 
  Receiving objects: 100% (18725/18725), 376.17 MiB | 171.00 KiB/s, done.
 
  Resolving deltas: 100% (1571/1571), done.
 
  Checking connectivity... done.
 
  Checking out files: 100% (18593/18593), done.
 
 
 
  $ du -sh
 
  1.1G .
 
 
 
 
 
However, for development / testing it is often better to have some of the repository history so that you can quickly load other versions to pin down a bug.
 
  
 
==  Push access  ==
 
==  Push access  ==

Revision as of 08:33, 29 December 2014

[edit]Compiling Wesnoth

Platforms

The Battle for Wesnoth code-base is stored in a version control repository. Version control allows the entire development team to edit files concurrently. The version control software tracks revisions, stores a record of all edits, and prevents simultaneous editing from causing clashes. All changes are stored in the version control repository.

When a release is planned, the current set of the files in the repository is frozen, given a release number, and shipped out to the world at large. Then, as files continue to be edited by the developers, the repository code advances past that point. The repository (or "repo") version is by definition the most up-to-date version of the code.

The Wesnoth repository is a Git repository and is hosted on GitHub: <https://github.com/wesnoth/wesnoth>.

Git

Git is the most widely used open-source version-control system. You can learn more about it at its website, <http://git-scm.com>.

Git replaced Sub­version (SVN) as Wesnoth's version-control system in March 2013. Sub­version had, itself, previously replaced an older program, Concurrent Versioning System (CVS), in 2005. These earlier systems have left a few traces in the version history which you might encounter; some older documentation and a few files refer to them.

Browse the code

There are currently two main streams of development ("branches"): the master branch (1.13.x), and the stable branch (1.12.x). (1.10.x is now oldstable.) Most other branches are only used for a short time to do some testing without disturbing the main development.

You can use a Web browser to view the source code at:

https://github.com/wesnoth/wesnoth

Download

To clone a copy of the repository into a directory called "wesnoth",

git clone "https://github.com/wesnoth/wesnoth.git" wesnoth
There are other transport protocols, in addition to Hypertext Transfer Protocol Secure (HTTPS), over which one can clone a Git repository from GitHub, including:
  • Secure Shell (SSH) ("ssh://git@github.com/wesnoth/wesnoth.git"), which provides a bit more security, and can be more convenient for developers, but needs to be set up first (see the "Push access" section, below).
  • Git's native transport protocol ("git://github.com/wesnoth/wesnoth.git"), which may be somewhat faster than HTTPS (though GitHub uses a faster "smart" HTTPS transport), but is insecure and should be used (if one must use it) with caution (check the commit hashes!).

A more detailed explanation is available here.

FAQ

Q: The repository is ~3 gigabytes, and my Internet connection is not stable enough to reliably download it. What should I do?

A: https://stackoverflow.com/questions/9268378/how-do-i-clone-a-large-git-repository-on-an-unreliable-connection

  1. Use a download manager to download the directory "https://github.com/wesnoth/wesnoth.git", in one or more sessions.
  2. Put this "wesnoth.git" directory, which is the internals of the Wesnoth repository, in a new, empty directory.
  3. Rename the "wesnoth.git" directory to ".git".
  4. Finally, run these commands in the directory that contains the ".git" directory:
$ git remote add remote "https://github.com/wesnoth/wesnoth.git"
$ git reset --hard HEAD

The first command links your local repository to the upstream repository; the second checks out a working tree (i.e., copies the files out of the ".git" directory into a form that you can use).


Q: I don't want any alternate branches or repository history. How could I avoid downloading that?

A: This simply requires a more elaborate command. For example, to only download the last revision of the 1.12 branch, and store it in a directory named "wesnoth-1.12-single-branch-test":

$ git clone --branch 1.12 --single-branch --depth 1 "https://github.com/wesnoth/wesnoth.git" wesnoth-1.12-single-branch-test

Example results:

$ git clone --branch 1.12 --single-branch --depth 1 "https://github.com/wesnoth/wesnoth.git" wesnoth-1.12-single-branch-test
Cloning into 'wesnoth-1.12-single-branch-test'...
remote: Counting objects: 18725, done.
remote: Compressing objects: 100% (17541/17541), done.
remote: Total 18725 (delta 1571), reused 7397 (delta 1004)
Receiving objects: 100% (18725/18725), 376.17 MiB | 171.00 KiB/s, done.
Resolving deltas: 100% (1571/1571), done.
Checking connectivity... done.
Checking out files: 100% (18593/18593), done.
$ du -sh wesnoth-1.12-single-branch-test # "du" means "disk usage".
1.1G	wesnoth-1.12-single-branch-test

However, for development and testing, it is often better to have some of the repository history, so that you can quickly check out older versions of the repository to pin down a bug.

Push access

For push access (the capability to push changes from your local repository) to our upstream repository on GitHub, you must have an account on GitHub, which must be registered as part of the Wesnoth group.

It may be convenient to use Secure Shell (SSH) transfer, so that you needn't enter your username and password each time you push commits, or insecurely store those credentials in an unencrypted configuration file. To do so, generate an SSH key pair with a command like (on Unix descendent operating systems like a Linux distribution or Apple OS X, at least) this:

ssh-keygen -t rsa -b 15360 -f <file> -C "<your name>'s SSH key for GitHub"

On Linux or Apple OS X, <file> would be, e.g., "~/.ssh/id-key-for-github".

Note that generating an SSH key pair can potentially take a while and be fairly CPU-intensive.

Then put the following into your SSH configuration file (on Unix descendent systems, this is "~/.ssh/config"):

Host github.com
	IdentityFile <file>

Then register the key with GitHub, by going to <https://github.com/settings/ssh>, selecting "Add SSH key", and pasting the contents of the public key file (<file>, but with a ".pub" extension) into the "Key" field.

Then, if you have not yet cloned the repository, clone it via SSH:

git clone git@github.com:wesnoth/wesnoth.git wesnoth

If you have already cloned the repository, you can set it to use SSH transfer:

git remote set-url origin git@github.com:wesnoth/wesnoth.git

Update

Do this from inside the wesnoth directory

git pull

Reviewing your changes

Before committing, it's always wise to run

git diff

and look at the output. Some kinds of mistakes that are hard to see embedded in all the code you have modified are more easily spotted in the isolated diff lines.

Generating patches

Under Git on a Unix-like operating system, you'll typically do

 git format-patch HEAD~1..HEAD

or something similar; "HEAD~1" may be replaced by a hash or symbolic reference to any earlier revision. This will produce one or more patch files, numbered and ending with the extension ".patch". See PatchSubmissionGuidelines for more on how to get these merged into the public repository.

Push to your own fork

If you have an account on GitHub, you can fork the repository and add your fork as a remote of your clone.

 git remote add fork git@github.com:YOUR_USERNAME/wesnoth.git

You can then push your branches to your fork:

git push fork branch_name

Or, if you want to push one branch in your local repository to another in the remote repository:

git push fork local_branch_name:remote_branch_name

You can then create pull requests from your branches in GitHub’s Web interface.

See Also