mirror of
https://github.com/evennia/evennia.git
synced 2026-03-18 13:56:30 +01:00
595 lines
No EOL
38 KiB
HTML
595 lines
No EOL
38 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html>
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
|
||
|
||
<title>Version Control — Evennia 1.0-dev documentation</title>
|
||
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script src="../_static/jquery.js"></script>
|
||
<script src="../_static/underscore.js"></script>
|
||
<script src="../_static/doctools.js"></script>
|
||
<script src="../_static/language_data.js"></script>
|
||
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
|
||
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</script>
|
||
<link rel="shortcut icon" href="../_static/favicon.ico"/>
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
</head><body>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href="">Version Control</a></li>
|
||
</ul>
|
||
<div class="develop">develop branch</div>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section class="tex2jax_ignore mathjax_ignore" id="version-control">
|
||
<h1>Version Control<a class="headerlink" href="#version-control" title="Permalink to this headline">¶</a></h1>
|
||
<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.</p>
|
||
<p>It’s strongly recommended that you put your game code under version control. Version
|
||
control is also the way to contribue to Evennia itself.</p>
|
||
<p>For an introduction to the concept, start with the Wikipedia article
|
||
<a class="reference external" href="https://en.wikipedia.org/wiki/Version_control">here</a>. Evennia uses the version
|
||
control system <a class="reference external" href="https://git-scm.com/">Git</a> and this is what will be covered
|
||
henceforth. Note that this page primarily shows commands for Linux, but the
|
||
syntax should be the same for Windows and Mac.</p>
|
||
<p>For more help on using Git, please refer to the <a class="reference external" href="https://help.github.com/articles/set-up-git#platform-all">Official GitHub
|
||
documentation</a>.</p>
|
||
<section id="setting-up-git">
|
||
<h2>Setting up Git<a class="headerlink" href="#setting-up-git" title="Permalink to this headline">¶</a></h2>
|
||
<p>You can find expanded instructions for
|
||
installation <a class="reference external" href="https://git-scm.com/book/en/Getting-Started-Installing-Git">here</a>.</p>
|
||
<section id="step-1-install-git">
|
||
<h3>Step 1: Install Git<a class="headerlink" href="#step-1-install-git" title="Permalink to this headline">¶</a></h3>
|
||
<ul>
|
||
<li><p><strong>Fedora Linux</strong></p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> yum install git-core
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p><strong>Debian Linux</strong> <em>(Ubuntu, Linux Mint, etc.)</em></p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> apt-get install git
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p><strong>Windows</strong>: It is recommended to use <a class="reference external" href="https://gitforwindows.org/">Git for Windows</a>.</p></li>
|
||
<li><p><strong>Mac</strong>: Mac platforms offer two methods for installation, one via MacPorts, which you can find
|
||
out about <a class="reference external" href="https://git-scm.com/book/en/Getting-Started-Installing-Git#Installing-on-Mac">here</a>, or
|
||
you can use the <a class="reference external" href="https://sourceforge.net/projects/git-osx-installer/">Git OSX Installer</a>.</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="step-2-define-user-e-mail-settings-for-git">
|
||
<h3>Step 2: Define user/e-mail Settings for Git<a class="headerlink" href="#step-2-define-user-e-mail-settings-for-git" title="Permalink to this headline">¶</a></h3>
|
||
<p>To avoid a common issue later, you will need to set a couple of settings; first you will need to
|
||
tell Git your username, followed by your e-mail address, so that when you commit code later you will
|
||
be properly credited.</p>
|
||
<blockquote>
|
||
<div><p>Note that your commit information will be visible to everyone if you ever contribute to Evennia or
|
||
use an online service like github to host your code. So if you are not comfortable with using your
|
||
real, full name online, put a nickname here.</p>
|
||
</div></blockquote>
|
||
<ol>
|
||
<li><p>Set the default name for git to use when you commit:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> git config --global user.name "Your Name Here"
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Set the default email for git to use when you commit:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> git config --global user.email "your_email@example.com"
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ol>
|
||
</section>
|
||
</section>
|
||
<section id="putting-your-game-folder-under-version-control">
|
||
<h2>Putting your game folder under version control<a class="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>
|
||
</div></blockquote>
|
||
<p>After you have set up your game you will have created a new folder to host your particular game
|
||
(let’s call this folder <code class="docutils literal notranslate"><span class="pre">mygame</span></code> for now).</p>
|
||
<p>This folder is <em>not</em> under version control at this point.</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git init mygame
|
||
</pre></div>
|
||
</div>
|
||
<p>Your mygame folder is now ready for version control! Add all the content and make a first
|
||
commit:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>cd mygame
|
||
git add *
|
||
git commit -a -m "Initial commit"
|
||
</pre></div>
|
||
</div>
|
||
<p>In turn these commands:</p>
|
||
<ul class="simple">
|
||
<li><p>Move us into the <code class="docutils literal notranslate"><span class="pre">mygame</span></code> folder</p></li>
|
||
<li><p>Tell <code class="docutils literal notranslate"><span class="pre">git</span></code> that everything <code class="docutils literal notranslate"><span class="pre">*</span></code> means everything) in this folder should be put
|
||
under version control.</p></li>
|
||
<li><p><em>Commit</em> all (<code class="docutils literal notranslate"><span class="pre">-a</span></code>) those newly added files to git and add a message <code class="docutils literal notranslate"><span class="pre">-m</span></code> so you remember
|
||
what you did at this point. Doing a commit is like saving a snapshot of the
|
||
current state of everything.</p></li>
|
||
</ul>
|
||
<p>Read on for details!</p>
|
||
<section id="tracking-files">
|
||
<h3>Tracking files<a class="headerlink" href="#tracking-files" title="Permalink to this headline">¶</a></h3>
|
||
<p>When working on your code or fix bugs in your local branches you may end up creating new files. If
|
||
you do you must tell Git to track them by using the add command.</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git add <filename>
|
||
</pre></div>
|
||
</div>
|
||
<p>You only need to do this once per file.</p>
|
||
<div class="highlight-none notranslate"><div class="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>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>You will notice that some files are not covered by your git version control,
|
||
notably your settings file (<code class="docutils literal notranslate"><span class="pre">mygame/server/conf/settings.py</span></code>) and your sqlite3
|
||
database file <code class="docutils literal notranslate"><span class="pre">mygame/server/evennia.db3</span></code>. What is auto-ignored by is controlled
|
||
by the hidden file <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">.gitignore</span></code>.</p>
|
||
</div>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>You should <em>never</em> put your sqlite3 database file into git by removing its entry
|
||
in <code class="docutils literal notranslate"><span class="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
|
||
backup-name.</p>
|
||
</div>
|
||
</section>
|
||
<section id="committing-your-code">
|
||
<h3>Committing your Code<a class="headerlink" href="#committing-your-code" title="Permalink to this headline">¶</a></h3>
|
||
<p><em>Committing</em> your code means storing the current snapshot of your code within
|
||
git. This creates a “save point” or “history” of your development process. You
|
||
can later jump back and forth in your history, for example to figure out just
|
||
when a bug was introduced or see what results the code used to produce compared
|
||
to now. Or just wiping everything since the last commit, if you did something
|
||
stupid.</p>
|
||
<p>It’s usually a good idea to commit your changes often. Committing is fast and
|
||
local only - you will never commit anything online at this point. To commit your
|
||
changes, use</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git commit --all
|
||
</pre></div>
|
||
</div>
|
||
<p>Also <code class="docutils literal notranslate"><span class="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>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git commit -a -m "This fixes a bug in the combat code."
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="changing-your-mind">
|
||
<h3>Changing your mind<a class="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
|
||
‘check out’ the file you want - this will re-load it from the last committed
|
||
state:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout <file_to_revert>
|
||
git checkout foo/bar/dummy.py
|
||
</pre></div>
|
||
</div>
|
||
<p>If you want to revert <em>all</em> changes you did since last commit, do</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout .
|
||
</pre></div>
|
||
</div>
|
||
<p>(that is, add a single <code class="docutils literal notranslate"><span class="pre">.</span></code> at the end).</p>
|
||
</section>
|
||
<section id="pushing-your-code-online">
|
||
<h3>Pushing your code online<a class="headerlink" href="#pushing-your-code-online" title="Permalink to this headline">¶</a></h3>
|
||
<p>So far your code is only located on your private machine. A good idea is to back
|
||
it up online. The easiest way to do this is to push it to your own remote
|
||
repository on GitHub.</p>
|
||
<div class="admonition important">
|
||
<p class="admonition-title">Important</p>
|
||
<p>Just to avoid confusion, be aware that Github’s documentation has changed to
|
||
calling the primary branch ‘main’ rather than ‘master’. While Evennia still
|
||
uses ‘master’ branch (and this is what we refer to below), you can use either
|
||
name for your personal primary branch - they are equivalent.</p>
|
||
</div>
|
||
<ol class="simple">
|
||
<li><p>Make sure you have your game directory setup under git version control as
|
||
described in the previous section. Make sure to commit any changes you did.</p></li>
|
||
<li><p>Create a new, empty repository on Github. Github explains how
|
||
<a class="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 <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">remote</span> <span class="pre">add</span> <span class="pre">origin</span> <span class="pre"><github</span> <span class="pre">URL></span></code> where
|
||
<code class="docutils literal notranslate"><span class="pre"><github</span> <span class="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><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">remote</span> <span class="pre">-v</span></code> to verify the online dir.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span> <span class="pre">origin</span> <span class="pre">master</span></code> (or <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span> <span class="pre">origin</span> <span class="pre">main</span></code>) now pushes your game dir
|
||
online so you can see it on <a class="reference external" href="http://github.com">github.com</a>.</p></li>
|
||
</ol>
|
||
<p>You can commit your work locally (<code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span> <span class="pre">--all</span> <span class="pre">-m</span> <span class="pre">"Make</span> <span class="pre">a</span> <span class="pre">change</span> <span class="pre">that</span> <span class="pre">..."</span></code>) as many times as you want. When you want to push those changes to your
|
||
online repo, you do <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span></code>. You can also <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">clone</span> <span class="pre"><url_to_online_repo></span></code>
|
||
from your online repo to somewhere else (like your production server) and
|
||
henceforth do <code class="docutils literal notranslate"><span class="pre">git</span> <span class="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>
|
||
</section>
|
||
</section>
|
||
<section id="forking-evennia">
|
||
<h2>Forking Evennia<a class="headerlink" href="#forking-evennia" title="Permalink to this headline">¶</a></h2>
|
||
<p>This helps you set up an online <em>fork</em> of the main Evennia repository so you can
|
||
easily commit fixes and help with upstream development. You can do this step
|
||
also if you <em>didn’t</em> put your game dir under version control like in the
|
||
previous section - the evennia repo and your game dir repo are completely
|
||
separate.</p>
|
||
<section id="step-1-fork-the-evennia-master-repository">
|
||
<h3>Step 1: Fork the evennia/master repository<a class="headerlink" href="#step-1-fork-the-evennia-master-repository" title="Permalink to this headline">¶</a></h3>
|
||
<blockquote>
|
||
<div><p>Before proceeding with the following step, make sure you have registered and
|
||
created an account on <a class="reference external" href="https://github.com/">GitHub.com</a>. This is necessary in order to create a fork
|
||
of Evennia’s master repository, and to push your commits to your fork either for
|
||
yourself or for contributing to
|
||
Evennia.</p>
|
||
</div></blockquote>
|
||
<p>A <em>fork</em> is a clone of the master repository that you can make your own commits
|
||
and changes to. At the top of <a class="reference external" href="https://github.com/evennia/evennia">this page</a>,
|
||
click the “Fork” button, as it appears below.
|
||
<img alt="" src="https://github-images.s3.amazonaws.com/help/bootcamp/Bootcamp-Fork.png" /></p>
|
||
</section>
|
||
<section id="step-2-clone-your-online-fork-of-evennia">
|
||
<h3>Step 2: Clone your online fork of Evennia<a class="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
|
||
command:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git clone https://github.com/yourusername/evennia.git
|
||
</pre></div>
|
||
</div>
|
||
<p>This will download your fork to your computer. It creates a new folder
|
||
<code class="docutils literal notranslate"><span class="pre">evennia/</span></code> at your current location.</p>
|
||
</section>
|
||
<section id="step-3-configure-remotes">
|
||
<h3>Step 3: Configure remotes<a class="headerlink" href="#step-3-configure-remotes" title="Permalink to this headline">¶</a></h3>
|
||
<p>Your Evennia-fork is now separate from upstream, ‘official’ Evennia. You will
|
||
want to set it up so that you can easily sync our updates and changes to your
|
||
fork.</p>
|
||
<p>We do this by setting up a new <em>remote</em>. We actually already have one remote,
|
||
that is our own github form of Evennia. This got created when you cloned the
|
||
repo and defaults to being called <code class="docutils literal notranslate"><span class="pre">origin</span></code>.</p>
|
||
<p>We will now create a new remote called <code class="docutils literal notranslate"><span class="pre">upstream</span></code>.</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>cd evennia
|
||
git remote add upstream https://github.com/evennia/evennia.git
|
||
</pre></div>
|
||
</div>
|
||
<p>This adds a remote to the main evennia repo.</p>
|
||
<p>If you also want to access Evennia’s <code class="docutils literal notranslate"><span class="pre">develop</span></code> branch (the bleeding edge
|
||
development) do the following:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git fetch upstream develop
|
||
git checkout develop
|
||
</pre></div>
|
||
</div>
|
||
<p>Use
|
||
git checkout master
|
||
git checkout develop</p>
|
||
<p>to switch between the branches. If you want to contribute a fix, ask first which
|
||
branch to use. Normally <code class="docutils literal notranslate"><span class="pre">master</span></code> is for bug fixes and <code class="docutils literal notranslate"><span class="pre">develop</span></code> is for new
|
||
features, but late in the development of a new Evennia version, all changes
|
||
often go into <code class="docutils literal notranslate"><span class="pre">develop</span></code>.</p>
|
||
</section>
|
||
</section>
|
||
<section id="working-with-your-evennia-fork">
|
||
<h2>Working with your Evennia fork<a class="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>
|
||
<section id="updating-to-latest-evennia">
|
||
<h3>Updating to latest Evennia<a class="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>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout master
|
||
git pull upstream master
|
||
</pre></div>
|
||
</div>
|
||
<p>Or, if you are working against Evennia’s development branch:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout develop
|
||
git pull upstream develop
|
||
</pre></div>
|
||
</div>
|
||
<p>The <code class="docutils literal notranslate"><span class="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>
|
||
<section id="making-changes">
|
||
<h3>Making changes<a class="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 <code class="docutils literal notranslate"><span class="pre">master</span></code> or
|
||
<code class="docutils literal notranslate"><span class="pre">develop</span></code> branches. Instead you make a <em>new</em> branch off the branch you want
|
||
and change <em>that</em>.</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout master (or develop)
|
||
check checkout -b strange_bug
|
||
</pre></div>
|
||
</div>
|
||
<p>You now have a new branch <code class="docutils literal notranslate"><span class="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
|
||
modifications.</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git branches
|
||
</pre></div>
|
||
</div>
|
||
<p>will show you which branches are available and which one you are currently
|
||
using. Use <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">checkout</span> <span class="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
|
||
<code class="docutils literal notranslate"><span class="pre">master</span></code>/<code class="docutils literal notranslate"><span class="pre">develop</span></code> branch and then <em>merge</em> those changes into your work branch.
|
||
Make sure you have committed everything first!</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git commit -a -m "My latest changes ..." # on your strange_bug branch
|
||
git checkout master (or develop)
|
||
git pull upstream develop
|
||
git checkout strange_bug
|
||
git merge master (or develop)
|
||
</pre></div>
|
||
</div>
|
||
<p>If everything went well, your <code class="docutils literal notranslate"><span class="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>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git commit -a -m "Fixed the issue in ..."
|
||
git commit -a -m "Adding unit tests. This resolves #123."
|
||
</pre></div>
|
||
</div>
|
||
<p>Use</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git diff
|
||
</pre></div>
|
||
</div>
|
||
<p>to see what you changed since last commit, and</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git log
|
||
</pre></div>
|
||
</div>
|
||
<p>to see past commits (including those made by Evennia upstream, remember that
|
||
your branch is a copy of the upstream one, including its history!)</p>
|
||
</section>
|
||
</section>
|
||
<section id="sharing-your-evennia-fixes-on-github">
|
||
<h2>Sharing your Evennia fixes on Github<a class="headerlink" href="#sharing-your-evennia-fixes-on-github" title="Permalink to this headline">¶</a></h2>
|
||
<p>Up to this point your <code class="docutils literal notranslate"><span class="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
|
||
then run the following:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git push -u origin strange_bug
|
||
</pre></div>
|
||
</div>
|
||
<p>You only need to do this once, the <code class="docutils literal notranslate"><span class="pre">-u</span></code> makes this the default push-location. In
|
||
the future, you can just push things online like this:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git push
|
||
</pre></div>
|
||
</div>
|
||
<section id="troubleshooting">
|
||
<h3>Troubleshooting<a class="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 <code class="docutils literal notranslate"><span class="pre">403:</span> <span class="pre">Forbidden</span> <span class="pre">Access</span></code> at this stage.
|
||
In that case, some users have reported that the workaround is to create a file
|
||
<code class="docutils literal notranslate"><span class="pre">.netrc</span></code> under your home directory and add your github credentials there:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>machine github.com
|
||
login <my_github_username>
|
||
password <my_github_password>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
<section id="making-an-evennia-pull-request">
|
||
<h2>Making an Evennia Pull Request<a class="headerlink" href="#making-an-evennia-pull-request" title="Permalink to this headline">¶</a></h2>
|
||
<p>If you think that the fixes you did in your <code class="docutils literal notranslate"><span class="pre">strange_bug</span></code> branch should be a
|
||
part of the regular Evennia, you should create a <em>Pull Request</em> (PR). This is a
|
||
call for the Evennia maintainer to pull your change into an upstream branch.</p>
|
||
<blockquote>
|
||
<div><p>It is wise to make separate branches for every fix or series of fixes you want
|
||
to contribute.</p>
|
||
</div></blockquote>
|
||
<p>Assuming you have followed the instructions above and have pushed your changes
|
||
online, <a class="reference external" href="https://github.com/evennia/evennia/pulls">create a pull request</a> and
|
||
follow the instructions. Make sure to specifically select your <code class="docutils literal notranslate"><span class="pre">strange_bug</span></code>
|
||
branch to be the source of the merge and use the branch you based that branch
|
||
off (<code class="docutils literal notranslate"><span class="pre">master</span></code> or <code class="docutils literal notranslate"><span class="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
|
||
branch:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git checkout master (or develope)
|
||
git pull upstream master (or develop)
|
||
</pre></div>
|
||
</div>
|
||
<p>Since your changes are now in upstream, your local <code class="docutils literal notranslate"><span class="pre">strange_bug</span></code> branch is now
|
||
superfluous and should be deleted:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git branch -D strange_bug
|
||
</pre></div>
|
||
</div>
|
||
<p>You can also safely delete your online <code class="docutils literal notranslate"><span class="pre">strange_bug</span></code> branch in your fork
|
||
(you can do this from the PR page on github).</p>
|
||
</section>
|
||
<section id="git-tips-and-tricks">
|
||
<h2>GIT tips and tricks<a class="headerlink" href="#git-tips-and-tricks" title="Permalink to this headline">¶</a></h2>
|
||
<p>Some of the GIT commands can feel a little long and clunky if you need to do them often. Luckily you
|
||
can create aliases for those. Here are some useful commands to run:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git st</span>
|
||
<span class="c1"># - view brief status info</span>
|
||
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">st</span> <span class="s1">'status -s'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Above, you only need to ever enter the <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">config</span> <span class="pre">...</span></code> command once - you have then added the new
|
||
alias. Afterwards, just do <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">st</span></code> to get status info. All the examples below follow the same
|
||
template.</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git cl</span>
|
||
<span class="c1"># - clone a repository</span>
|
||
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">cl</span> <span class="n">clone</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git cma "commit message"</span>
|
||
<span class="c1"># - commit all changes without opening editor for message</span>
|
||
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">cma</span> <span class="s1">'commit -a -m'</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git ca</span>
|
||
<span class="c1"># - amend text to your latest commit message</span>
|
||
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">ca</span> <span class="s1">'commit --amend'</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git fl</span>
|
||
<span class="c1"># - file log; shows diffs of files in latest commits</span>
|
||
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">fl</span> <span class="s1">'log -u'</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git co [branchname]</span>
|
||
<span class="c1"># - checkout</span>
|
||
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">co</span> <span class="n">checkout</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git br <branchname></span>
|
||
<span class="c1"># - create branch</span>
|
||
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">br</span> <span class="n">branch</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git ls</span>
|
||
<span class="c1"># - view log tree</span>
|
||
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">ls</span> <span class="s1">'log --pretty=format:"%C(green)%h\ %C(yellow)[</span><span class="si">%a</span><span class="s1">d]%Cred</span><span class="si">%d</span><span class="se">\</span>
|
||
<span class="s1">%Creset</span><span class="si">%s</span><span class="s1">%Cblue\ [</span><span class="si">%c</span><span class="s1">n]" --decorate --date=relative --graph'</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git diff</span>
|
||
<span class="c1"># - show current uncommitted changes</span>
|
||
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">diff</span> <span class="s1">'diff --word-diff'</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># git grep <query></span>
|
||
<span class="c1"># - search (grep) codebase for a search criterion</span>
|
||
<span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">alias</span><span class="o">.</span><span class="n">grep</span> <span class="s1">'grep -Ii'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>To get a further feel for GIT there is also <a class="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
|
||
(which in turn makes it a lot more intuitive to use).</p>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
<div class="clearer"></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<p class="logo"><a href="../index.html">
|
||
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
|
||
</a></p>
|
||
<div id="searchbox" style="display: none" role="search">
|
||
<h3 id="searchlabel">Quick search</h3>
|
||
<div class="searchformwrapper">
|
||
<form class="search" action="../search.html" method="get">
|
||
<input type="text" name="q" aria-labelledby="searchlabel" />
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
</div>
|
||
<script>$('#searchbox').show(0);</script>
|
||
<p><h3><a href="../index.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">Version Control</a><ul>
|
||
<li><a class="reference internal" href="#setting-up-git">Setting up Git</a><ul>
|
||
<li><a class="reference internal" href="#step-1-install-git">Step 1: Install Git</a></li>
|
||
<li><a class="reference internal" href="#step-2-define-user-e-mail-settings-for-git">Step 2: Define user/e-mail Settings for Git</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#putting-your-game-folder-under-version-control">Putting your game folder under version control</a><ul>
|
||
<li><a class="reference internal" href="#tracking-files">Tracking files</a></li>
|
||
<li><a class="reference internal" href="#committing-your-code">Committing your Code</a></li>
|
||
<li><a class="reference internal" href="#changing-your-mind">Changing your mind</a></li>
|
||
<li><a class="reference internal" href="#pushing-your-code-online">Pushing your code online</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#forking-evennia">Forking Evennia</a><ul>
|
||
<li><a class="reference internal" href="#step-1-fork-the-evennia-master-repository">Step 1: Fork the evennia/master repository</a></li>
|
||
<li><a class="reference internal" href="#step-2-clone-your-online-fork-of-evennia">Step 2: Clone your online fork of Evennia</a></li>
|
||
<li><a class="reference internal" href="#step-3-configure-remotes">Step 3: Configure remotes</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#working-with-your-evennia-fork">Working with your Evennia fork</a><ul>
|
||
<li><a class="reference internal" href="#updating-to-latest-evennia">Updating to latest Evennia</a></li>
|
||
<li><a class="reference internal" href="#making-changes">Making changes</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#sharing-your-evennia-fixes-on-github">Sharing your Evennia fixes on Github</a><ul>
|
||
<li><a class="reference internal" href="#troubleshooting">Troubleshooting</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#making-an-evennia-pull-request">Making an Evennia Pull Request</a></li>
|
||
<li><a class="reference internal" href="#git-tips-and-tricks">GIT tips and tricks</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<div role="note" aria-label="source link">
|
||
<!--h3>This Page</h3-->
|
||
<ul class="this-page-menu">
|
||
<li><a href="../_sources/Coding/Version-Control.md.txt"
|
||
rel="nofollow">Show Page Source</a></li>
|
||
</ul>
|
||
</div><h3>Links</h3>
|
||
<ul>
|
||
<li><a href="https://www.evennia.com">Home page</a> </li>
|
||
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
|
||
<li><a href="http://games.evennia.com">Game Index</a> </li>
|
||
<li>
|
||
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
|
||
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
|
||
<a href="https://evennia.blogspot.com/">Blog</a>
|
||
</li>
|
||
</ul>
|
||
<h3>Versions</h3>
|
||
<ul>
|
||
<li><a href="Version-Control.html">1.0-dev (develop branch)</a></li>
|
||
</ul>
|
||
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href="">Version Control</a></li>
|
||
</ul>
|
||
<div class="develop">develop branch</div>
|
||
</div>
|
||
<div class="footer" role="contentinfo">
|
||
© Copyright 2020, The Evennia developer community.
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
|
||
</div>
|
||
</body>
|
||
</html> |