<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>
<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>
<li><p>Move us into the <codeclass="docutils literal notranslate"><spanclass="pre">mygame</span></code> folder</p></li>
<li><p>Tell <codeclass="docutils literal notranslate"><spanclass="pre">git</span></code> that everything <codeclass="docutils literal notranslate"><spanclass="pre">*</span></code> means everything) in this folder should be put
under version control.</p></li>
<li><p><em>Commit</em> all (<codeclass="docutils literal notranslate"><spanclass="pre">-a</span></code>) those newly added files to git and add a message <codeclass="docutils literal notranslate"><spanclass="pre">-m</span></code> so you remember
what you did at this point. Doing a commit is like saving a snapshot of the
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>git status
</pre></div>
</div>
<p>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 question
mark in front of them.</p>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<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>. What is auto-ignored by 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 <codeclass="docutils literal notranslate"><spanclass="pre">.gitignore</span></code>.</p>
</div>
<divclass="admonition warning">
<pclass="admonition-title">Warning</p>
<p>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 drive to a
<p>Also <codeclass="docutils literal notranslate"><spanclass="pre">-a</span></code> works. This will open a text editor for you to describe your change.
Be brief but informative in your message - you’ll appreciate it later. When you
save and close the editor, the commit will be saved. You can create the message
directly with</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>git commit -a -m "This fixes a bug in the combat code."
<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> (or <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">push</span><spanclass="pre">origin</span><spanclass="pre">main</span></code>) now pushes your game dir
online so you can see it on <aclass="reference external"href="http://github.com">github.com</a>.</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 you specifically grant access.</p>
<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>
<h3>Step 2: Clone your online fork of Evennia<aclass="headerlink"href="#step-2-clone-your-online-fork-of-evennia"title="Permalink to this headline">¶</a></h3>
<p>The fork only exists online as of yet. In a terminal, change your directory to
the folder you wish to develop in. From this directory run the following
<p>to switch between the branches. If you want to contribute a fix, ask first which
branch to use. Normally <codeclass="docutils literal notranslate"><spanclass="pre">master</span></code> is for bug fixes and <codeclass="docutils literal notranslate"><spanclass="pre">develop</span></code> is for new
features, but late in the development of a new Evennia version, all changes
often go into <codeclass="docutils literal notranslate"><spanclass="pre">develop</span></code>.</p>
</section>
</section>
<sectionid="working-with-your-evennia-fork">
<h2>Working with your Evennia fork<aclass="headerlink"href="#working-with-your-evennia-fork"title="Permalink to this headline">¶</a></h2>
<p><em>Branches</em> are stand-alone editions of the same code. You make a commit to a
branch. Switching to a branch will change the code on-disk. You can easily
make a new branch off a parent branch, and then merge it back into the same
branch later (or throw it away). This is a very common way to work on new
features in safety and isolation.</p>
<sectionid="updating-to-latest-evennia">
<h3>Updating to latest Evennia<aclass="headerlink"href="#updating-to-latest-evennia"title="Permalink to this headline">¶</a></h3>
<p>When Evennia’s official repository updates, first make sure to commit all your
changes to your branch and then checkout the “clean” master branch:</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">pull</span></code> command will fetch all the changes from the “upstream” remote and
merge it into your local master/develop branch. It should now be a perfect copy
of the latest Evennia changes.</p>
</section>
<sectionid="making-changes">
<h3>Making changes<aclass="headerlink"href="#making-changes"title="Permalink to this headline">¶</a></h3>
<p>As a rule of thumb you should <em>never</em> work directly in Evennia’s <codeclass="docutils literal notranslate"><spanclass="pre">master</span></code> or
<codeclass="docutils literal notranslate"><spanclass="pre">develop</span></code> branches. Instead you make a <em>new</em> branch off the branch you want
<p>You now have a new branch <codeclass="docutils literal notranslate"><spanclass="pre">strange_bug</span></code> that is an exact replica of the branch you
had checked out when you created it. Here you can now make your own
<p>will show you which branches are available and which one you are currently
using. Use <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">checkout</span><spanclass="pre"><branch></span></code> to move between them, but remember to commit
your changes before you do.</p>
<p>You often want to make sure also your work-branch has the latest upstream
changes. To do this, you need to first update your copy of the
<codeclass="docutils literal notranslate"><spanclass="pre">master</span></code>/<codeclass="docutils literal notranslate"><spanclass="pre">develop</span></code> branch and then <em>merge</em> those changes into your work branch.
Make sure you have committed everything first!</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>git commit -a -m "My latest changes ..." # on your strange_bug branch
<p>If everything went well, your <codeclass="docutils literal notranslate"><spanclass="pre">strange_bug</span></code> branch will now have the latest version
of Evennia merged with whatever changes you have done.</p>
<p>Now work away on your code and commit with reasonable commit messages</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>git commit -a -m "Fixed the issue in ..."
git commit -a -m "Adding unit tests. This resolves #123."
<h2>Sharing your Evennia fixes on Github<aclass="headerlink"href="#sharing-your-evennia-fixes-on-github"title="Permalink to this headline">¶</a></h2>
<p>Up to this point your <codeclass="docutils literal notranslate"><spanclass="pre">strange_bug</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
<p>You only need to do this once, the <codeclass="docutils literal notranslate"><spanclass="pre">-u</span></code> makes this the default push-location. In
the future, you can just push things online like this:</p>
<h3>Troubleshooting<aclass="headerlink"href="#troubleshooting"title="Permalink to this headline">¶</a></h3>
<p>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 github credentials there:</p>
<p>Assuming you have followed the instructions above and have pushed your changes
online, <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">strange_bug</span></code>
branch to be the source of the merge and use the branch you based that branch
off (<codeclass="docutils literal notranslate"><spanclass="pre">master</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">develop</span></code>) as the target.</p>
<p>Evennia developers will then be able to examine your request and merge it if
it’s deemed suitable. They may also come back with feedback and request you do
some changes.</p>
<p>Once approved and merged, your change will now be available in the upstream
<p>Since your changes are now in upstream, your local <codeclass="docutils literal notranslate"><spanclass="pre">strange_bug</span></code> branch is now
<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 it</a> - it’s a bit long but it will help you understand the underlying ideas behind GIT
