![[Burning Cog]](../../../icons/pyromaniac.png){kind=icon}
Introduction
Git is a source control management system used across the world for storing and managing software repositories. It is a distributed source control system designed to allow multiple stands of changes to be made by different individuals and brought together. In addition to a large user base, git scales well between managing small and large projects. It is the defacto industry standard for modern software development.
The PyromaniacGit module provides an interface from within RISC OS to the Git source control management tool provided by the host system. By interfacing to the host system, it avoids needing to provide a native RISC OS implementation and provides many of the facilities that are expected by such a tool.
Overview
The Git source control system is used the world over, and many documents describe its usage far better than can be done justice here. However, a short overview of how the source control system can be used may help to illustrate a common case.
Making changes to an existing repository
One of the most common operations with Git is to make changes to an existing repository. The workflow may differ depending on whether you are continuing making changes, where the repository lives, and your preferences, but in general the workflow will be something like this:
- Locate the repository you wish to change. This might mean finding the repository online, or within the local filesystem.
- Clone the repository to a working directory where you will make changes. This copies the repository and its history to your local system so that you can examine and use the files locally.
- Create a new branch. The branch allows you to keep your changes away from the original code and describes what is being modified.
- Modify some files to do what you want.
- Build, test or otherwise check that they do actually do what you want.
- Stage the changes for commit. This marks them as being ready for commit as a checkpoint that you may return to. You can continue to modify files after this, and then stage more changes later.
- Commit the changes. This places the staged files in the repository's history.
- Push the changes to the original repository. This makes the changes available to other people.
- Invite others to review the changes and comment on them.
- Make changes to based on the comments.
- Stage, commit and push, as before. Repeat the review process.
- Merge the changes from your branch into the original code.
Terminology
Within the Git management system there are many terms and phrases which are used to describe operations. The core Git documentation describes many of these in greater detail, and with greater accuracy, than here. However, it is useful to include some of the terms here as an introduction.
| Name | Meaning |
|---|---|
| Repository | A Git Repository is a collection of the details about an entire software project's history and its meta data. It contains historic change details in the differences in files, the annotations made as commit messages, details about who made them and when, and administrative information such as branches and tags. The repository is usually local when it is being worked on, but can be transferred to remote servers so that others may work with it. The repository files are usually stored in the '.git' directory within the working directory. |
| Working directory | The working directory is where source files have been checked out at a given point in history. The working directory may be clean (having no changes compared to the version stored in the repository) or dirty (having changed files). |
| Branch | A branch is a continuation of development which has diverged from another branch, which has been given a name. A Git repository has at least one branch, but commonly has many branches for work in progress, releases or just to store ideas. A branch can contain any number of changes to source files. |
| Commit | The history of changes within a repository is organised by 'commits'. Each commit is a collection of the changes that have been made to the files within the repository, and some information about those changes. Associate with the commit is a message describing the changes and metadata such as the name of the author of the change and the date that it occurred. A commit is identified by a unique identifier - a hash called the 'SHA' - which can be used to return to that point in time. The act of creating a new commit in the history is called 'committing'. |
| Index | 'Index' is the slightly confusing name for files which have been staged for commit. The name comes from the way in which the files are stored internally. Staged files in the index are safe and you can revert your current changes to the point at which they were added to the 'index'. The index only exists in the local repository, and is not visible to anyone else. To make the staged files available to others, and remove them from the 'index', they must be committed. Files in the index are also referred to as having been 'cached'. |
| Staging | Staging is the act of marking some changes as being a good checkpoint by moving them to the index. Files that have been staged may be committed, or they be compared to the current working directory, or the working directory can be reverted to that checkpoint. |
| Merge | A merge is when two (or more) branches of development are brought together into a single branch. A merge is usually made when the changes on a branch have been reviewed and are felt to be acceptable for use in a branch. However, the merge can go the other way as well. If the original branch has had changes made to it, it can be useful to merge the original branch into another, to 'catch up' with the original. |
| Clone | To work with any repository, it is necessary to take a copy of it, together with its history. This is called 'cloning' the repository. The clone is a snapshot of the current state of that repository. The original repository may have other people work with it, and so it may be necessary to 'pull' more changes later, to catch up to the latest version. |
| Remote repository | A repository present on your system usually has a remote repository associated with it. The remote repository usually has a simple name like 'origin'. Changes in your local repository may be pushed to the remote repository to publish them for others to see. The remote repository may have its changes pulled into your local repository so that you can see changes that other people have made. |
| Fetch | A remote repository will be updated by other people. In order for you to see those changes, it is necessary to fetch the changes from the repository. Fetching the changes will make them available to your local repository but not modify any local branches or your working directory. |
| Pull | When changes are made to a remote repository it is usually necessary to pull them into your branch. The 'pull' operation is actually a combination of fetching the changes from the remote repository, and then merging those changes into your current branch. |
| Pull Request | A 'Pull request', sometimes called a 'PR' or 'Merge request' is a request for a set of changes which you have made to be reviewed by the original author (or others) with the intention of merging the change into the original branch. The term is a misnomer these days, as the 'pull request' is usually a 'push' of the changes to a remote repository, which is then reviewed before merging with a branch. |
| Diff | A 'diff' is a set of differences between two versions of a file. Usually a diff is represented by lines that have been removed (usually indicated by a '-' prefix) and lines that have been added (usually indicated by a '+' prefix). A 'diff' is also used to refer to a collection of these differences for files which make up a given change or commit. |
Technical details
The Git implementation provided by RISC OS Pyromaniac is as faithful as it can be to the original unix version of the Git tool. There are differences and features which are not implemented - particularly those which are more advanced and are not required for day-to-day usage of sources.
The PyromaniacGit tool does not make assumptions or allowances for the version of Git which is installed on the host system. As such, your experience may differ if an earlier or later version of the host git tool is installed. Git commands such as 'git switch' only exist on later versions of the git tool, but they are provided nonetheless by the PyromaniacGit implementation. If a command is not supported by the host git, an error will be reported.
RISC OS specifics
The tool applies certain restrictions and has some changes from the original, in order to match with the way in which RISC OS functions. To the average user these will not be noticed, but it is useful to be aware of where the behaviour is different.
Filenames and filetypes
Files used by the PyromaniacGit tool must live on the host filesystem and be accessible to the host git tool. When a filename is supplied to the *Git tool, it should be preceeded by a '--' sequence to ensure that it is clear that a filename is expected. Filenames will be converted from the RISC OS format to the native format before being supplied to the host git tool.
This has an effect on how the files are handled when it comes to filetypes. Filetypes are part of the filename in the host storage for RISC OS Pyromaniac, and as such the filename supplied on the command line will be expanded to include a filetype.
Certain commands such as *Git revparse --show-toplevel are only used to generate filenames. These commands are processed to turn the host filename format into RISC OS filename format. However, these commands are the exception rather than the rule. In most other cases, filenames output by PyromaniacGit will appear in host format. Commands such as *Git status will therefore use the host filename format.
This may change in the future, but it is a current limitation.
Identifier alphabets
Within Git on other systems, identifiers are expected to be supplied in UTF-8 format. However, RISC OS does not generally use UTF-8 for its input or output, and relies on a global configuration called the alphabet. PyromaniacGit will convert identifiers from the global alphabet to UTF-8 before passing these to the host git tool. This includes identifiers such as:
- Repository names
- Branch names
- Tag names
Messages supplied to the Git tool (for example, on commit) on the command line with the '-m' switch, or within files with the '--file' switch, will also be converted from the current alphabet to UTF-8 before being passed to the host tool.
All output from the tool is converted from UTF-8 to the current alphabet before being passed to the RISC OS VDU system.
This means that if you type *Git branch £, a branch named '£' will be created using the UTF-8 encoding, and if you type *Git branch, the branch name will appear as the pound sign character, as expected.
System variables
The original git system uses environment variables to configure some settings within the system. These variables are in the usual POSIX form of capital letters, separated by underscores. This is not the RISC OS way of doing things, so the variables used by the RISC OS clients are similar to those names, but use mixed case and separated by '$' between the common sections.
There are a lot of environment variables which can be set, not all of which make sense under RISC OS. The system variables are documented within this chapter. Many of the variables follow the same pattern, in the original system, which is replicated on RISC OS.
- Variables which specify a file or directory name are given in RISC OS format and will be converted before being passed to the host git command.
- Variables which specify a list of files or directory names are given in RISC OS format, separated by commas. In the original, they would be separated by colons, but a colon is part of the filename specification on RISC OS.
- Variables which may trace different parts of the code, may be specified with a RISC OS filename, or a number.
- Variables which specify names (such as the committer or author names) are converted from the current alphabet to UTF-8.
Information about the system variables can also be obtained through the command *Help GitVariables.
Output colour translation
Output from the PyromaniacGit tool is expected to be at the command line by users. As such the tool is able to convert the colour control sequences (often called ANSI or VT control codes) into RISC OS text selection sequences. This means that the output you see within RISC OS will most closely resemble that which you would have seen in a non-RISC OS environment.
In particular this means that the output from *Git diff and *Git log are coloured to make it easier to read them.
Configuration file
The configuration file, usually '.gitconfig' in your home directory, would be used to set up some configuration. This file is not available under PyromaniacGit as it introduces some significant security problems. This can be overridden in the configuration, but should not be necessary for most uses.
Some git configuration options have been made available as separate PyromanigGit configuration options which can be specified through the *PyromaniacConfig or the '--config' command line switch.
This includes the configuration of the credentials store, which keeps track of the authentication details used for remote operations. This can be set in RISC OS using the system variable Git$Credentials$Store.
User identification
Usually the identification of the user is derived from the system's user name and host name, if it is not configured in the configuration file or environment variables. PyromaniacGit offers system variables which will provide these names, as there is no default on RISC OS Pyromaniac for a user name. The variable is set by default to dummy values from the RISC OS Pyromaniac configuration.
Remote authentication
Authentication with a remote server is usually by entering user and password details with a prompt. This is implemented within RISC OS Pyromaniac by a callback to RISC OS to request the user name and password details, and will by default be passed to the standard SWI OS_ReadLine interface.
Under the original git system, the credentials management would be set in the configuration file. PyromaniacGit offers a single management system based on the 'credential store'. The credential store places the credentials in a file, which will be used first when authentication is needed for a server. The credentials store is managed as a RISC OS filename given by Git$Credentials$Store.
Editing messages
When committing code, and for certain operations like 'rebase', it is necessary to supply a message or edit text. Under the original git system this launches the user's configured editor to perform this operation.
Under PyromaniacGit, the request to edit text in this way is passed to the 'TextEditor' system, as used by the Twin module for its editing. By default this is configured to use the host's 'nano' editor (which is common on POSIX systems, but might not be present under Windows). However, if the TextEditor is configured to use a different editor system, the Git system will use this as well. This means that, for example, when configued to use the 'wxwidgets' text editor, a UI window will be opened to edit the content.
Supported operations
The PyromaniacGit implementation does not support all the operations that can be performed by the standard git tool. However, most day to day operations are supported. This should allow both new and regular users of git to use the system as they would expect.
For more details, see *Git.
System variables
The system variable Git$AlternateObjectDirectories is equivalent to the POSIX environment variable GIT_ALTERNATE_OBJECT_DIRECTORIES.
List of comma separated object directories to search.
Format: List of directory names in RISC OS format, separated by commas.
The system variable Git$AskPass is equivalent to the POSIX environment variable GIT_ASKPASS.
Tool to invoke to request passwords from the user. Not supported under RISC OS Pyromaniac.
The system variable Git$Author$Date is equivalent to the POSIX environment variable GIT_AUTHOR_DATE.
Timestamp used for the "author" field.
The system variable Git$Author$Email is equivalent to the POSIX environment variable GIT_AUTHOR_EMAIL.
Email address for the "author" field.
The system variable Git$Author$Name is equivalent to the POSIX environment variable GIT_AUTHOR_NAME.
Human readable name in the "author" field.
Format: A string in the current RISC OS alphabet.
The system variable Git$CeilingDirectories is equivalent to the POSIX environment variable GIT_CEILING_DIRECTORIES.
List of comma separated directories above which we should not search for .git.
Format: List of directory names in RISC OS format, separated by commas.
The system variable Git$Committer$Date is equivalent to the POSIX environment variable GIT_COMMITTER_DATE.
Timestamp used for the "committer" field.
The system variable Git$Committer$Email is equivalent to the POSIX environment variable GIT_COMMITTER_EMAIL.
Email address for the "committer" field.
The system variable Git$Committer$Name is equivalent to the POSIX environment variable GIT_COMMITTER_NAME.
Human readable name in the "committer" field.
Format: A string in the current RISC OS alphabet.
The system variable Git$Common$Dir is equivalent to the POSIX environment variable GIT_COMMON_DIR.
Absolute directory to search for non-worktree files.
Format: Directory or filename in RISC OS format (which must exist).
The system variable Git$Config$Count is equivalent to the POSIX environment variable GIT_CONFIG_COUNT.
Count of the configuration variables supplied in Git$Config$Key$# and Git$ Config$Value$#. Not supported under RISC OS Pyromaniac.
The system variable Git$Config$Global is equivalent to the POSIX environment variable GIT_CONFIG_GLOBAL.
User configuration, which on POSIX would be ~/.gitconfig. Not supported under RISC OS Pyromaniac.
Format: Directory or filename in RISC OS format.
The system variable Git$Config$NoSystem is equivalent to the POSIX environment variable GIT_CONFIG_NOSYSTEM.
Disable the system git configuration if set to non-empty. Not supported under RISC OS Pyromaniac.
The system variable Git$Config$System is equivalent to the POSIX environment variable GIT_CONFIG_SYSTEM.
System configuration filename, which on POSIX would be /etc/gitconfig. Not supported under RISC OS Pyromaniac.
Format: Directory or filename in RISC OS format.
The system variable Git$Diff$External is equivalent to the POSIX environment variable GIT_EXTERNAL_DIFF.
Tool to invoke to perform diffs. Not supported under RISC OS Pyromaniac.
The system variable Git$Diff$Opts is equivalent to the POSIX environment variable GIT_DIFF_OPTS.
Options for performing diffs.
The system variable Git$Diff$PathCounter is equivalent to the POSIX environment variable GIT_DIFF_PATH_COUNTER.
Counter of the path being processed, supplied to the external diff tool. Not supported under RISC OS Pyromaniac.
The system variable Git$Diff$PathTotal is equivalent to the POSIX environment variable GIT_DIFF_PATH_TOTAL.
Total paths being processed, supplied to the external diff tool. Not supported under RISC OS Pyromaniac.
The system variable Git$Editor is equivalent to the POSIX environment variable GIT_EDITOR.
Tool used to edit messages. Not supported under RISC OS Pyromaniac.
The system variable Git$Flush is equivalent to the POSIX environment variable GIT_FLUSH.
Flush output stream more regularly when set to "1".
The system variable Git$GitDir is equivalent to the POSIX environment variable GIT_DIR.
Location of the .git directory.
Format: Directory or filename in RISC OS format.
The system variable Git$Index$File is equivalent to the POSIX environment variable GIT_INDEX_FILE.
Name of the index file to use, eg "/tmp-index".
Format: Directory or filename in RISC OS format.
The system variable Git$Merge$Verbosity is equivalent to the POSIX environment variable GIT_MERGE_VERBOSITY.
How verbose the recursive merge should be (0-5).
The system variable Git$Namespace is equivalent to the POSIX environment variable GIT_NAMESPACE.
Names ref namespace to use.
The system variable Git$ObjectDirectory is equivalent to the POSIX environment variable GIT_OBJECT_DIRECTORY.
Absolute directory for the "objects".
Format: Directory or filename in RISC OS format (which must exist).
The system variable Git$OptionalLocks is equivalent to the POSIX environment variable GIT_OPTIONAL_LOCKS.
Avoids taking locks when run in the background when set to "0".
The system variable Git$Pager is equivalent to the POSIX environment variable GIT_PAGER.
Tool used to page output to the terminal. Not supported under RISC OS Pyromaniac.
The system variable Git$PathSpecs$Glob is equivalent to the POSIX environment variable GIT_GLOB_PATHSPECS.
Treat all path specs as globs.
The system variable Git$PathSpecs$ICase is equivalent to the POSIX environment variable GIT_ICASE_PATHSPECS.
Treat all path specs as case-insensitive.
The system variable Git$PathSpecs$Literal is equivalent to the POSIX environment variable GIT_LITERAL_PATHSPECS.
Treat all path specs as literal, rather than globs.
The system variable Git$PathSpecs$NoGlob is equivalent to the POSIX environment variable GIT_NOGLOB_PATHSPECS.
Treat all path specs as literal.
The system variable Git$ProgressDelay is equivalent to the POSIX environment variable GIT_PROGRESS_DELAY.
Seconds before showing the progress indicator.
The system variable Git$Protocol is equivalent to the POSIX environment variable GIT_PROTOCOL.
Set key-value pairs for the low level protocol.
The system variable Git$Protocol$Allow is equivalent to the POSIX environment variable GIT_ALLOW_PROTOCOL.
A colon-separated list of protocols which are allowed.
The system variable Git$Protocol$FromUser is equivalent to the POSIX environment variable GIT_PROTOCOL_FROM_USER.
Prevent protocols used by fetch/push/clone configured to user state when set to "0".
The system variable Git$RefLogAction is equivalent to the POSIX environment variable GIT_REFLOG_ACTION.
Records a reason for an action in the reflog.
Format: A string in the current RISC OS alphabet.
The system variable Git$RefParanoia is equivalent to the POSIX environment variable GIT_REF_PARANOIA.
Include broken or badly named refs when set to "1".
The system variable Git$SSH$Command is equivalent to the POSIX environment variable GIT_SSH_COMMAND.
Tool to invoke in place of SSH to connect to an SSH host.. Not supported under RISC OS Pyromaniac.
The system variable Git$SSH$Variant is equivalent to the POSIX environment variable GIT_SSH_VARIANT.
Type of SSH tool supplied in Git$SSH$Command. Not supported under RISC OS Pyromaniac.
The system variable Git$TerminalPrompt is equivalent to the POSIX environment variable GIT_TERMINAL_PROMPT.
Disables prompt if set to "0".
The system variable Git$Trace is equivalent to the POSIX environment variable GIT_TRACE.
Enable general trace messages (0, 1, 2 for levels, or filename).
Format: The number 0, 1, 2 or a filename in RISC OS format.
The system variable Git$Trace$CURL is equivalent to the POSIX environment variable GIT_TRACE_CURL.
Enable trace messages for network transfers (0, 1, 2 for levels, or filename).
Format: The number 0, 1, 2 or a filename in RISC OS format.
The system variable Git$Trace$CURL$NoData is equivalent to the POSIX environment variable GIT_TRACE_CURL_NO_DATA.
Enable trace messages for network transfers without the data dumps (0, 1, 2 for levels, or filename).
Format: The number 0, 1, 2 or a filename in RISC OS format.
The system variable Git$Trace$CURL$RedactCookies is equivalent to the POSIX environment variable GIT_REDACT_COOKIES.
Hide the cookies named in this variable when tracing.
The system variable Git$Trace$PackAccess is equivalent to the POSIX environment variable GIT_TRACE_PACK_ACCESS.
Enable trace messages for access to packs (0, 1, 2 for levels, or filename ).
Format: The number 0, 1, 2 or a filename in RISC OS format.
The system variable Git$Trace$PackFile is equivalent to the POSIX environment variable GIT_TRACE_PACKFILE.
Enable trace messages for packfiles (0, 1, 2 for levels, or filename).
Format: The number 0, 1, 2 or a filename in RISC OS format.
The system variable Git$Trace$Packet is equivalent to the POSIX environment variable GIT_TRACE_PACKET.
Enable trace messages for transfers between programs (0, 1, 2 for levels).
Format: The number 0, 1, 2 or a filename in RISC OS format.
The system variable Git$Trace$Performance is equivalent to the POSIX environment variable GIT_TRACE_PERFORMANCE.
Enable performance related trace messages (0, 1, 2 for levels, or filename ).
Format: The number 0, 1, 2 or a filename in RISC OS format.
The system variable Git$Trace$Setup is equivalent to the POSIX environment variable GIT_TRACE_SETUP.
Enable trace messages for the early setup of the system (0, 1, 2 for levels, or filename).
Format: The number 0, 1, 2 or a filename in RISC OS format.
The system variable Git$Trace$Shallow is equivalent to the POSIX environment variable GIT_TRACE_SHALLOW.
Enable trace messages for shallow repositories (0, 1, 2 for levels, or filename).
Format: The number 0, 1, 2 or a filename in RISC OS format.
The system variable Git$Trace2 is equivalent to the POSIX environment variable GIT_TRACE2.
Enable more detailed trace messages (0, 1, 2 for levels, or filename).
Format: The number 0, 1, 2 or a filename in RISC OS format.
The system variable Git$Trace2$Event is equivalent to the POSIX environment variable GIT_TRACE2_EVENT.
Enable JSON formatted trace messages (0, 1, 2 for levels, or filename).
Format: The number 0, 1, 2 or a filename in RISC OS format.
The system variable Git$Trace2$Perf is equivalent to the POSIX environment variable GIT_TRACE2_PERF.
Enable column based trace messages (0, 1, 2 for levels, or filename).
Format: The number 0, 1, 2 or a filename in RISC OS format.
The system variable Git$WorkTree is equivalent to the POSIX environment variable GIT_WORK_TREE.
Location of the root for your work tree.
Format: Directory or filename in RISC OS format (which must exist).
Filename to store credentials in (instead of ~/.git-credentials).
*Commands
<help> | - | Request help on the command given, or on git in general if no command name given. |
<command> | - | Command to perform (or to obtain help on, in the case of the 'help' command). |
<subcommand> | - | Variant of the command to perform. |
The *Git command is used to perform operations on the Git source control management system. Under RISC OS Pyromaniac it interfaces indirectly with the native 'git' tool. Each of the commands has a different syntax, which can be obtained using the command *Git help command>.
The commands currently supported by git are:
| Name | Meaning |
|---|---|
| add | Add file contents to the index |
| annotate | Annotate file lines with commit information |
| blame | Show what revision and author last modified each line of a file |
| branch | List, create, or delete branches |
| checkout | Switch branches or restore working tree files |
| cherry-pick | Apply the changes introduced by some existing commits |
| clean | Remove untracked files from the working tree |
| clone | Clone a repository into a new directory |
| commit | Record changes to the repository |
| describe | Give an object a human readable name based on an available ref |
| diff | Show changes between commits, commit and working tree, etc |
| fetch | Fetch from another repository or a local branch |
| grep | Print lines matching a pattern |
| help | Display help for a given command |
| init | Create an empty Git repository or reinitialize an existing one |
| log | Show commit logs |
| merge | Join two or more development histories together |
| mv | Move or rename a file or directory |
| pull | Fetch from and integrate with another repository or a local branch |
| push | Push to a remote repository |
| rebase | Reapply commits on top of another base tip |
| reflog | Manage reflog information |
| remote |
Manage set of tracked repositories. Supported subcommands:
|
| reset | Reset current HEAD to the specified state |
| restore | Restore working tree files |
| rev-parse | Pick out and massage parameters |
| rm | Remove files from the working tree and from the index |
| shortlog | Summarize 'git log' output |
| show | Show various types of objects |
| stash |
Stash the changes in a dirty working directory away. Supported subcommands:
|
| status | Show the working tree status |
| switch | Switch branches |
| tag | Create, list, and delete tags on objects |
| version | Report the version of git on the host and RISC OS system |