<p>Version control software allows you to track the changes you make to your code, as well as being
able to easily backtrack these changes, share your development efforts and more. Even if you are not
contributing to Evennia itself, and only wish to develop your own MU* using Evennia, having a
version control system in place is a good idea (and standard coding practice). For an introduction
to the concept, start with the Wikipedia article
<aclass="reference external"href="http://en.wikipedia.org/wiki/Version_control">here</a>. Evennia uses the version control system
<aclass="reference external"href="https://git-scm.com/">Git</a> and this is what will be covered henceforth. Note that this page also
deals with commands for Linux operating systems, and the steps below may vary for other systems,
however where possible links will be provided for alternative instructions.</p>
<p>For more help on using Git, please refer to the <aclass="reference external"href="https://help.github.com/articles/set-up-git#platform-all">Official GitHub
<h3>Step 2: Define user/e-mail Settings for Git<aclass="headerlink"href="#step-2-define-user-e-mail-settings-for-git"title="Permalink to this headline">¶</a></h3>
<li><p>Set the default name for git to use when you commit:</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="n">git</span><spanclass="n">config</span><spanclass="o">--</span><spanclass="k">global</span><spanclass="n">user</span><spanclass="o">.</span><spanclass="n">name</span><spanclass="s2">"Your Name Here"</span>
</pre></div>
</div>
</li>
<li><p>Set the default email for git to use when you commit:</p>
<h2>Putting your game folder under version control<aclass="headerlink"href="#putting-your-game-folder-under-version-control"title="Permalink to this headline">¶</a></h2>
<blockquote>
<div><p>Note: The game folder’s version control is completely separate from Evennia’s repository.</p>
<p>You can check the current status of version control with <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">status</span></code>. This will show if you have
any modified, added or otherwise changed files. Some files, like database files, logs and temporary
PID files are usually <em>not</em> tracked in version control. These should either not show up or have a
<p>You will notice that some files are not covered by your git version control, notably your settings
file (<codeclass="docutils literal notranslate"><spanclass="pre">mygame/server/conf/settings.py</span></code>) and your sqlite3 database file <codeclass="docutils literal notranslate"><spanclass="pre">mygame/server/evennia.db3</span></code>.
This is controlled by the hidden file <codeclass="docutils literal notranslate"><spanclass="pre">mygame/.gitignore</span></code>. Evennia creates this file as part of the
creation of your game directory. Everything matched in this file will be ignored by GIT. If you want
to, for example, include your settings file for collaborators to access, remove that entry in
<div><p>Note: You should <em>never</em> put your sqlite3 database file into git by removing its entry in
<codeclass="docutils literal notranslate"><spanclass="pre">.gitignore</span></code>. GIT is for backing up your code, not your database. That way lies madness and a good
chance you’ll confuse yourself so that after a few commits and reverts don’t know what is in your
database or not. If you want to backup your database, do so by simply copying the file on your hard
<p>This will save all changes you made since last commit. The command will open a text editor where you
can add a message detailing the changes you’ve made. Make it brief but informative. You can see the
history of commits with <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">log</span></code>. If you don’t want to use the editor you can set the message
directly by using the <codeclass="docutils literal notranslate"><spanclass="pre">-m</span></code> flag:</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="n">git</span><spanclass="n">commit</span><spanclass="o">--</span><spanclass="nb">all</span><spanclass="o">-</span><spanclass="n">m</span><spanclass="s2">"This fixes a bug in the combat code."</span>
</pre></div>
</div>
</div>
<divclass="section"id="changing-your-mind">
<h3>Changing your mind<aclass="headerlink"href="#changing-your-mind"title="Permalink to this headline">¶</a></h3>
<p>If you have non-committed changes that you realize you want to throw away, you can do the following:</p>
<p>This will revert the file to the state it was in at your last <codeclass="docutils literal notranslate"><spanclass="pre">commit</span></code>, throwing away the changes
you did to it since. It’s a good way to make wild experiments without having to remember just what
you changed. If you do <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">checkout</span><spanclass="pre">.</span></code> you will throw away <em>all</em> changes since the last commit.</p>
<li><p>Make sure you have your game directory setup under git version control as described above. Make
sure to commit any changes.</p></li>
<li><p>Create a new, empty repository on Github. Github explains how
<aclass="reference external"href="https://help.github.com/articles/create-a-repo/">here</a> (do <em>not</em> “Initialize the repository with a
README” or else you’ll create unrelated histories).</p></li>
<li><p>From your local game dir, do <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">remote</span><spanclass="pre">add</span><spanclass="pre">origin</span><spanclass="pre"><github</span><spanclass="pre">URL></span></code> where <codeclass="docutils literal notranslate"><spanclass="pre"><github</span><spanclass="pre">URL></span></code> is the URL
to your online repo. This tells your game dir that it should be pushing to the remote online dir.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">remote</span><spanclass="pre">-v</span></code> to verify the online dir.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">push</span><spanclass="pre">origin</span><spanclass="pre">master</span></code> now pushes your game dir online so you can see it on github.com.</p></li>
<p>You can commit your work locally (<codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">commit</span><spanclass="pre">--all</span><spanclass="pre">-m</span><spanclass="pre">"Make</span><spanclass="pre">a</span><spanclass="pre">change</span><spanclass="pre">that</span><spanclass="pre">..."</span></code>) as many times as
you want. When you want to push those changes to your online repo, you do <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">push</span></code>. You can also
<codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">clone</span><spanclass="pre"><url_to_online_repo></span></code> from your online repo to somewhere else (like your production
server) and henceforth do <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">pull</span></code> to update that to the latest thing you pushed.</p>
<p>Note that GitHub’s repos are, by default publicly visible by all. Creating a publicly visible online
clone might not be what you want for all parts of your development process - you may prefer a more
private venue when sharing your revolutionary work with your team. If that’s the case you can change
your repository to “Private” in the github settings. Then your code will only be visible to those
<h3>Step 1: Fork the evennia/master repository<aclass="headerlink"href="#step-1-fork-the-evennia-master-repository"title="Permalink to this headline">¶</a></h3>
<p>This will download your fork to your computer. It creates a new folder <codeclass="docutils literal notranslate"><spanclass="pre">evennia/</span></code> at your current
<p>A <em>remote</em> is a repository stored on another computer, in this case on GitHub’s server. When a
repository is cloned, it has a default remote called <codeclass="docutils literal notranslate"><spanclass="pre">origin</span></code>. This points to your fork on GitHub,
not the original repository it was forked from. To easily keep track of the original repository
(that is, Evennia’s official repository), you need to add another remote. The standard name for this
remote is “upstream”.</p>
<p>Below we change the active directory to the newly cloned “evennia” directory and then assign the
original Evennia repository to a remote called “upstream”:</p>
<p>If you also want to access Evennia’s <codeclass="docutils literal notranslate"><spanclass="pre">develop</span></code> branch (the bleeding edge development branch) do the
<p>You should now have the upstream branch available locally. You can use this instead of <codeclass="docutils literal notranslate"><spanclass="pre">master</span></code>
below if you are contributing new features rather than bug fixes.</p>
<p>This command will checkout and automatically create the new branch <codeclass="docutils literal notranslate"><spanclass="pre">myfixes</span></code> on your machine. If you
stared out in the master branch, <em>myfixes</em> will be a perfect copy of the master branch. You can see
which branch you are on with <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">branch</span></code> and change between different branches with <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">checkout</span><spanclass="pre"><branchname></span></code>.</p>
<p>Branches are fast and cheap to create and manage. It is common practice to create a new branch for
every bug you want to work on or feature you want to create, then create a <em>pull request</em> for that
branch to be merged upstream (see below). Not only will this organize your work, it will also make
sure that <em>your</em> master branch version of Evennia is always exactly in sync with the upstream
<p>If everything went well, your <codeclass="docutils literal notranslate"><spanclass="pre">myfixes</span></code> branch will now have the latest version of Evennia merged
with whatever changes you have done. Use <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">log</span></code> to see what has changed. You may need to restart
the server or run <codeclass="docutils literal notranslate"><spanclass="pre">manage.py</span><spanclass="pre">migrate</span></code> if the database schema changed (this will be seen in the
commit log and on the mailing list). See the <aclass="reference external"href="http://git-scm.com/documentation">Git manuals</a> for
learning more about useful day-to-day commands, and special situations such as dealing with merge
<p>Up to this point your <codeclass="docutils literal notranslate"><spanclass="pre">myfixes</span></code> branch only exists on your local computer. No one else can see it.
If you want a copy of this branch to also appear in your online fork on GitHub, make sure to have
checked out your “myfixes” branch and then run the following:</p>
<p>This will create a new <em>remote branch</em> named “myfixes” in your online repository (which is refered
to as “origin” by default); the <codeclass="docutils literal notranslate"><spanclass="pre">-u</span></code> flag makes sure to set this to the default push location.
Henceforth you can just use <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">push</span></code> from your myfixes branch to push your changes online. This is
a great way to keep your source backed-up and accessible. Remember though that by default your
repository will be public so everyone will be able to browse and download your code (same way as you
can with Evennia itself). If you want secrecy you can change your repository to “Private” in the
Github settings. Note though that if you do, you might have trouble contributing to Evennia (since
we can’t see the code you want to share).</p>
<p><em>Note: If you hadn’t setup a public key on GitHub or aren’t asked for a username/password, you might
get an error <codeclass="docutils literal notranslate"><spanclass="pre">403:</span><spanclass="pre">Forbidden</span><spanclass="pre">Access</span></code> at this stage. In that case, some users have reported that the
workaround is to create a file <codeclass="docutils literal notranslate"><spanclass="pre">.netrc</span></code> under your home directory and add your credentials there:</em></p>
<p>To contribute you need to have <aclass="reference external"href="Coding/Version-Control.html#forking-evennia">forked Evennia</a> first. As described
above you should do your modification in a separate local branch (not in the master branch). This
branch is what you then present to us (as a <em>Pull request</em>, PR, see below). We can then merge your
change into the upstream master and you then do <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">pull</span></code> to update master usual. Now that the
master is updated with your fixes, you can safely delete your local work branch. Below we describe
<p>It is wise to make separate branches for every fix or series of fixes you want to contribute. You
are now in your new <codeclass="docutils literal notranslate"><spanclass="pre">fixing_strange_bug</span></code> branch. You can list all branches with <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">branch</span></code> and
jump between branches with <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">checkout</span><spanclass="pre"><branchname></span></code>. Code and test things in here, committing as
<p>You can make multiple commits if you want, depending on your work flow and progress. Make sure to
always make clear and descriptive commit messages so it’s easy to see what you intended. To refer
to, say, issue number 123, write <codeclass="docutils literal notranslate"><spanclass="pre">#123</span></code>, it will turn to a link on GitHub. If you include the text
“Resolves #123”, that issue will be auto-closed on GitHub if your commit gets merged into main
<div><p>If you refer to in-game commands that start with <codeclass="docutils literal notranslate"><spanclass="pre">@</span></code>(such as <codeclass="docutils literal notranslate"><spanclass="pre">@examine</span></code>), please put them in
backticks `, for example `@examine`. The reason for this is that GitHub uses <codeclass="docutils literal notranslate"><spanclass="pre">@username</span></code> to refer
to GitHub users, so if you forget the ticks, any user happening to be named <codeclass="docutils literal notranslate"><spanclass="pre">examine</span></code> will get a
<p>If you implement multiple separate features/bug-fixes, split them into different branches if they
are very different and should be handled as separate PRs. You can do any number of commits to your
branch as you work. Once you are at a stage where you want to show the world what you did you might
want to consider making it clean for merging into Evennia’s master branch by using <aclass="reference external"href="https://www.git-scm.com/book/en/v2/Git-Branching-Rebasing">git
rebase</a> (this is not always necessary,
and if it sounds too hard, say so and we’ll handle it on our end).</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">-u</span></code> flag is only needed the first time - this tells GIT to create a remote branch. If you
already created the remote branch earlier, just stand in your <codeclass="docutils literal notranslate"><spanclass="pre">fixing_strange_bug</span></code> branch and do
<p>Now you should tell the Evennia developers that they should consider merging your brilliant changes
into Evennia proper. <aclass="reference external"href="https://github.com/evennia/evennia/pulls">Create a pull request</a> and follow
the instructions. Make sure to specifically select your <codeclass="docutils literal notranslate"><spanclass="pre">fixing_strange_bug</span></code> branch to be the source
of the merge. Evennia developers will then be able to examine your request and merge it if it’s
deemed suitable.</p>
<p>Once your changes have been merged into Evennia your local <codeclass="docutils literal notranslate"><spanclass="pre">fixing_strange_bug</span></code> can be deleted
(since your changes are now available in the “clean” Evennia repository). Do</p>
<p>to delete your work branch. Update your master branch (<codeclass="docutils literal notranslate"><spanclass="pre">checkout</span><spanclass="pre">master</span></code> and then <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">pull</span></code>) and
you should get your fix back, now as a part of official Evennia!</p>
<p>Above, you only need to ever enter the <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">config</span><spanclass="pre">...</span></code> command once - you have then added the new
alias. Afterwards, just do <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">st</span></code> to get status info. All the examples below follow the same
<spanclass="c1"># - commit all changes without opening editor for message</span>
<spanclass="n">git</span><spanclass="n">config</span><spanclass="o">--</span><spanclass="k">global</span><spanclass="n">alias</span><spanclass="o">.</span><spanclass="n">cma</span><spanclass="s1">'commit -a -m'</span>
<p>To get a further feel for GIT there is also <aclass="reference external"href="https://www.youtube.com/watch?v=1ffBJ4sVUb4#t=1m58s">a good YouTube talk about
