README.GIT

Git Instructions:
-----------------

    For those who think git might be a bit too complicated to deal with,
    here are (I think) the minimal commands. See the "SUDO" section in
    README.sudo for ideas to make updating Xastir even simpler.


USERS:
------

    Initial Copy (Git Clone):
    -------------------------

    0) Make sure git is installed on your system.
     
    1) Run
        git config --global user.name "Your Name" user.email "Your@email.address"

        The above is not strictly necessary, but if you ever try to make changes
        to Xastir and get them integrated with the project it is important.

        NOTE: If you already have a different git global config, you can create
        a local config for a particular repo by going into that repo and doing:
        git config --local user.name "Your Name" user.email "Your@email.address"

        Check the config by:
            git config --local -l
            git config --global -l
            git config -l   # Doesn't differentiate between global and local though!

    2) Go to <http://github.com/Xastir/Xastir> to access the project page.
        There you will find the URL of the git repository, just to the
        right of a button that says "HTTPS". Copy this URL to your clipboard.

        (At the time of this writing, the URL was
         <https://github.com/Xastir/Xastir.git>)
     
    3) Open a shell, navigate to a directory where you want to store
        the Xastir source code, and enter this command:

        git  clone https://github.com/Xastir/Xastir.git
        
        This will create a clone of the Xastir git repository in an
        "Xastir" subdirectory of the current directory.
        
    All done!  You now have the latest development sources on your computer.
    Not only that, you have a complete copy of the entire project history
    and access to all prior releases.

    4) Please set your default git commit message template for the project to
       the one included in the Xastir source tree:

       cd Xastir
       cp git_commit_message_template ~
       git config --global commit.template ~/git_commit_message_template

       This will assure that when you make commits, your editor will start
       with a template that helps guide you through the process of writing
       commit messages that conform to the guidelines below in the section
       titled "Important: Git Commit Message Format".  This template is quite
       generic and conforms to the guidelines of many other open source
       projects, so it is reasonable to make it a global git option.

    Updating Your Copy:
    -------------------

    cd Xastir
    git pull           # Update your local repo (May be dangerous for developers)
    ./bootstrap.sh     # "autoreconf -i" also works
    mkdir -p build     # Build in a separate directory
    cd build
    ../configure
    (make clean;make -j3 2>&1) | tee make.log
    sudo make install  # "make install-strip" can be used after the first
                       # time: It removes debugging info from executable
    sudo chmod 4555 /usr/local/bin/xastir  # Only needed if using kernel AX.25
    xastir &   # Start it up!

    Note that you'll need autoconf 2.53 or newer and automake 1.6.3 or newer
    in order to run the "./bootstrap.sh" script.

    -or-

    Bypass all of the commands above and just type:
        cd Xastir
        ./update-xastir


   NOTE: "autoreconf", a part of the autoconf package, does the same
   thing that bootstrap.sh does, in a more modern approach.  The
   bootstrap.sh approach is very old and was the approach advocated by
   this document for many years, but invoking "autoreconf -i" does the
   same thing.

   PLEASE NOTE: Bootstrap.sh is used by both methods above, even
   "update-xastir", which is simply a script that performs all the
   steps listed explicitly earlier.

   The bootstrap.sh script is what creates the configure script.
   Running bootstrap.sh requires having autoconf and automake
   installed, and it will fail if these are not installed.  If
   bootstrap.sh fails, configure won't exist.  If bootstrap.sh fails,
   stop, fix the problem and try again.  There is no point continuing
   if bootstrap.sh gives you error messages about programs not being
   found (aclocal, autoconf, automake).

   This is a common problem reported to the Xastir team, and its solution
   is always the same:  install all prerequisite tools before trying to
   build Xastir.

DEVELOPERS:
-----------

    Initial Checkout:
    -----------------

    HTTPS Method:
      git clone https://github.com/Xastir/Xastir

    -or-

    SSH Method. Add keys to GitHub and then:

      git clone git@github.com:Xastir/Xastir

    Note that using the SSH method means that you won't have to answer the
    popups for user/password each time you do anything with the remote repo,
    although you will have to enter a passphrase if you added a passphrase to
    your SSH key. The SSH method is highly recommended for active developers! 


    Normal Development Flow:
    ------------------------

    A pull before committing can be dangerous, if there are substantial
    conflicts between your work and others (not very likely with Xastir, but
    definitely likely in bigger projects). It is much better to do a fetch
    (which pulls down changes from the remote but DOESN'T merge them into your
    tracking branch), then look at what changed upstream, and then either a
    merge, rebase, stash/pop, or something else depending on the level of
    conflict you see. See README.GIT.

    Doing a pull before starting your own work is reasonable, but if someone
    pushes while you're working (again, not very likely with Xastir), you can
    still wind up with really ugly history, with weird merge commits and
    undesired branching.

    On the other hand, if you replace "git pull" with "git pull --rebase" in
    that recipe, with the caveat that sometimes you might have to be more
    careful and that you need to understand what you're doing, a lot of the
    danger of the simple git pull can be avoided.

    We will often be working on a branch for development, then merging that
    branch with the trunk when that feature or bug-fix is ready for prime-time.

    Commit your work to your LOCAL repo:

       - First add all desired changes to the staging area:
           git add <file1>  <file2> <file3> ...

       - Then commit your staged changes to your local repo

          git commit

    Push your local repo changes up to GitHub when you are ready to
    publish them:

       git push


    Important: Git Commit Message Format
    ------------------------------------

    Git commit messages need to be in a certain format to make the best use
    of the "git log" commands. In particular the first line needs to be 50
    chars or less, then a BLANK LINE, then a detailed commit message. See
    this link for more info:

    http://chris.beams.io/posts/git-commit/


    Checking Out A Branch:
    ----------------------

    All branches associated with the Xastir project are contained in the clone
    you made earlier. You can switch your current working directory to
    one of those branches easily:

    cd Xastir
    git fetch (this updates your local repo copy from github, but doesn't
               merge changes into your working tree)
    git checkout <branch name>    (this switches all the files in your working
                                   tree to match those in the branch)
    git merge                     (This makes sure that all the changes that
                                   may have happened upstream on that branch
                                   get into your copy)

    You do not have to do this in a new directory --- so long as
    you haven't changed any files in the source tree, git checkout
    automatically swaps out all files it knows about with versions from the
    branch.

    If you really want to keep more than one branch's code around to work on,
    you can do that if you have git version 2.5 or later with the following
    commands:

    cd Xastir
    git worktree add <path> <branchname>

    This will create a new directory tree called <path> with the named
    branch checked out into it.

    In early 2018, there is only one active branch, the master branch,
    and we will be performing releases by creating release branches.

    There are many more git commands and options. Many of them are more of
    use to the developers. Some of those are listed below. The above should
    be enough for most people to keep their copies in sync with the latest git
    development sources.


    If Using Multiple GitHub Accounts:
    ----------------------------------

    You may have trouble getting your commits attributed to the correct GitHub
    login. GitHub uses the username/email in your git config settings for
    attribution. If it is wrong, you may have to do some of the below in order
    to set a LOCAL username and email for the one repository.

    The user.name and user.email are pulled from the global git config, but a
    local git config inside each repo will override those settings.

    Go to root of checked-out repo and set local user.name and user.email for
    this repo:

       git config user.name <github username>
       git config user.email <email address>
       git config -l           # Shows both local and global settings, hard to tell which is which
       git config --global     # Shows global settings
       git config --local -l   # Shows local repo configs, so should show new settings

    Another method (but more error-prone) of editing local/global git config is:

       git config edit             # Edit local config
       git config --global edit    # Edit global config

    If new commits still aren't using the right email, make sure you have not
    set GIT_COMMITTER_EMAIL or GIT_AUTHOR_EMAIL environment variables. 


    More Info:
    ----------

    Make sure you know how git works. Read https://git-scm.com/book/en/v2

    If you are very familiar with CVS, get used to working differently, because
    git is different.

    Read and understand http://chris.beams.io/posts/git-commit/

    Read http://justinhileman.info/article/changing-history/

    Read http://think-like-a-git.net/

    Read "Visual Git Cheat Sheet" at http://ndpsoftware.com/git-cheatsheet.html

    Branching and merging in git is very simple, and is documented very well
    by all those links. We will not repeat it here.

    If you use SSH, set up your SSH keys on GitHub and do the "git clone" using
    the SSH path. This will save you having to put in your password each time
    you use the remote repository, although if you added a passphrase to your
    SSH key you'll have to enter that each time.

    Useful Git Commands:
    --------------------

    Set up global user/email
        git config --global user.name "Your Name"
        git config --global user.email "user@domain.com"

    Set up user/email for a local repository
        cd /path/repository
        git config user.name "Your Name"
        git config user.email "user@domain.com"

    Configure Git's editor:
        git config --global core.editor /path/to/editor

    Colorizing Git output (set once and forget):
        git config --global color.ui auto

    Clone a repo:
        git clone http://github.com/Xastir/Xastir
        git clone https://github.com/Xastir/Xastir
        git clone git@github.com:Xastir/Xastir

    Status of local repo:
        git status

    Diff for a file:
        git diff <filename>

    See all branches, local and remote:
        git branch -a

    Visual Git viewer:
        gitk (tcl/tk and generic X11 viewer, comes with git)
        or
        gitg (gnome git viewer)

    Add files to the staging area:
        git add <file1> <file2>

    Commit changes to LOCAL repo:
        git commit      # If have files in staging area already
        git commit <file1> <file2>  # Ignores staging area

    Push local changes to remote repository:
        git push

    Update local repo from remote repo
        git fetch

    Update local repo and merge remote/local changes in local repo (May be
    dangerous for developers with modified code in their working tree):
        git pull

    Rebase local changes against latest master branch
        git fetch
        git rebase master


------------------------------------------------------------------------
Copyright (C) 2000-2023 The Xastir Group