mirror of
https://github.com/tmate-io/tmate.git
synced 2025-01-11 16:38:47 +01:00
Make some tweaks to NOTES and add a paragraph on git rather than huge PATCHES
file.
This commit is contained in:
Nicholas Marriott
parent
3a545376f0
commit
8249fbfb60
45
NOTES
45
NOTES
@ -5,9 +5,7 @@ to be accessed and controlled from a single terminal. tmux is intended to be a
|
||||
simple, modern, BSD-licensed alternative to programs such as GNU screen.
|
||||
|
||||
This release runs on OpenBSD, FreeBSD, NetBSD, Linux and OS X and may still
|
||||
run on Solaris and AIX (although they haven't been tested in a while). It is
|
||||
usable, although there remain a number of missing features and some remaining
|
||||
bugs are expected.
|
||||
run on Solaris and AIX (although they haven't been tested in a while).
|
||||
|
||||
If upgrading from 1.5, PLEASE NOTE:
|
||||
- The word-separators window option is now a session option.
|
||||
@ -25,57 +23,56 @@ To build tmux from a release tarball, do:
|
||||
$ ./configure && make
|
||||
$ sudo make install
|
||||
|
||||
To build from a version control checkout, the configure script must be
|
||||
generated by running:
|
||||
To get and build the latest version control checkout:
|
||||
|
||||
$ git clone git://tmux.git.sourceforge.net/gitroot/tmux/tmux
|
||||
$ cd tmux
|
||||
$ sh autogen.sh
|
||||
$ ./configure && make
|
||||
|
||||
tmux consists of a server part and multiple clients. The server is created when
|
||||
required and runs continuously unless killed by the user. Clients access the
|
||||
server through a socket in /tmp. Multiple sessions may be created on a single
|
||||
server and attached to a number of clients. Each session may then have a number
|
||||
of windows and windows may be linked to a number of sessions. Commands are
|
||||
available to create, rename and destroy windows and sessions; to attach and
|
||||
detach sessions from client terminals; to set configuration options; to split
|
||||
windows into several simultaneously displayed panes; and to bind and unbind
|
||||
command keys (invoked preceded by a prefix key, by default ctrl-b). Please see
|
||||
the tmux(1) man page for further information.
|
||||
For more information see https://sourceforge.net/scm/?type=git&group_id=200378
|
||||
and http://git-scm.com.
|
||||
|
||||
A more extensive, but rough, todo list is included in the TODO file.
|
||||
For documentation on using tmux, see the tmux.1 manpage. It can be viewed from
|
||||
the source tree with:
|
||||
|
||||
tmux also depends on several features of the client terminal (TERM), if these
|
||||
are missing it may refuse to run, or not behave correctly.
|
||||
$ nroff -mdoc tmux.1|less
|
||||
|
||||
Some common questions are answered in the FAQ file and a more extensive (but
|
||||
slightly out of date) guide is available in the OpenBSD FAQ at
|
||||
http://www.openbsd.org/faq/faq7.html#tmux. A rough todo list is in the TODO
|
||||
file.
|
||||
|
||||
A Vim syntax file is available in the examples directory. To install it:
|
||||
|
||||
- Drop the file in the syntax directory in your runtimepath (such as
|
||||
- Drop the file in the syntax directory into runtimepath (such as
|
||||
~/.vim/syntax/tmux.vim).
|
||||
- Make the filetype recognisable by adding the following to filetype.vim
|
||||
in your runtimepath (~/.vim/filetype.vim):
|
||||
(~/.vim/filetype.vim):
|
||||
|
||||
augroup filetypedetect
|
||||
au BufNewFile,BufRead .tmux.conf*,tmux.conf* setf tmux
|
||||
augroup END
|
||||
|
||||
- Switch on syntax highlighting by adding "syntax enable" to your vimrc file.
|
||||
- Switch on syntax highlighting by adding "syntax enable" to .vimrc.
|
||||
|
||||
For debugging, running tmux with -v or -vv will generate server and client log
|
||||
files in the current directory.
|
||||
|
||||
tmux mailing lists are available; visit:
|
||||
tmux mailing lists are available. The visit:
|
||||
|
||||
https://sourceforge.net/mail/?group_id=200378
|
||||
|
||||
Bug reports, feature suggestions and especially code contributions are most
|
||||
welcome. Please send by email to:
|
||||
|
||||
nicm@users.sf.net
|
||||
tmux-users@lists.sourceforge.net
|
||||
|
||||
This file and the CHANGES, FAQ and TODO files are licensed under the ISC
|
||||
license. Files under examples/ remain copyright their authors unless otherwise
|
||||
stated in the file but permission has been received to distribute them with
|
||||
tmux. All other files have a license and copyright notice at their
|
||||
start. Please contact me with any queries.
|
||||
start.
|
||||
|
||||
-- Nicholas Marriott <nicm@users.sf.net>
|
||||
|
||||
|
||||
153
PATCHES
153
PATCHES
@ -1,153 +0,0 @@
|
||||
Submitting Patches
|
||||
==================
|
||||
|
||||
Repository Overview
|
||||
===================
|
||||
|
||||
The portable version of tmux uses git [1], a distributed revision control system. This
|
||||
document is not intended to explain the git internals, for that there's
|
||||
already a wealth of documentation on the Internet.
|
||||
|
||||
The main portable tmux git repository [2] has one branch reflecting on-going
|
||||
development: "master". Release points of tmux are tagged and are available
|
||||
as git tags.
|
||||
|
||||
When submitting a patch, the feature should be made on top of the
|
||||
master branch.
|
||||
|
||||
Preamble
|
||||
========
|
||||
|
||||
If you've never used git before, git tracks meta-data about the committer
|
||||
and the author, as part of a commit, hence:
|
||||
|
||||
$ git config [--global] user.name "Your name"
|
||||
$ git config [--global] user.email "you@example.com"
|
||||
|
||||
Note that, if you already have this in the global ~/.gitconfig option, then
|
||||
this will be used. Setting this per-repository would involve not using the
|
||||
"--global" flag above. If you wish to use the same credentials always,
|
||||
pass the "--global" option, as shown.
|
||||
|
||||
This is a one-off operation once the repository has been cloned, assuming
|
||||
this information has ever been set before.
|
||||
|
||||
Coding style
|
||||
============
|
||||
|
||||
Since tmux is inherently an OpenBSD project, please see the OpenBSD style(9)
|
||||
guide:
|
||||
|
||||
http://www.openbsd.org/cgi-bin/man.cgi?query=style&apropos=0&sektion=0&manpath=OpenBSD+Current&arch=i386&format=html
|
||||
|
||||
It is expected that patches to tmux honour this guideline.
|
||||
|
||||
Use of topic branches
|
||||
=====================
|
||||
|
||||
Git's use of branches makes it very easy to separate out different topics
|
||||
from one another -- hence, for any feature or patch developed, they should
|
||||
be done in their own topic branch, which is branched from the current HEAD
|
||||
of origin/master. Hence:
|
||||
|
||||
$ git checkout master
|
||||
$ git pull
|
||||
$ git checkout my-new-feature
|
||||
|
||||
Which at this point on means that you're on the "my-new-feature" branch, and
|
||||
can then hack away. When you've got a series of changes, it's best to
|
||||
consider how to commit them. Blindly doing:
|
||||
|
||||
$ git commit -a
|
||||
|
||||
which would commit all changes, won't make for a easy patch review, and will
|
||||
likely just pollute the main git history with unnecessary noise. Not to
|
||||
mention, if a bug is discovered, finding it in amongst a huge code commit
|
||||
like that would be rather annoying. So instead, stage all the changes
|
||||
you're doing logically together -- break up the feature into four or five
|
||||
patches, or how ever many made sense.
|
||||
|
||||
For example, if you were writing a new feature, you might have:
|
||||
|
||||
* A patch to include any new header files.
|
||||
* A patch for any new function prototypes.
|
||||
* A patch per new function as it's written (or more, depending on the
|
||||
complexity).
|
||||
|
||||
This is nothing more than doing a:
|
||||
|
||||
$ git add foo.h
|
||||
$ git commit
|
||||
|
||||
[Write commit message]
|
||||
|
||||
... do some more hacking.
|
||||
|
||||
$ git add main.c
|
||||
$ git add utilities.c
|
||||
$ git commit
|
||||
|
||||
Working out what's changed
|
||||
==========================
|
||||
|
||||
Once you're happy with the commits on the "my-new-feature" branch, you'll
|
||||
obviously want to check that they still work on top of any new code that
|
||||
might have been committed to the master* branch since you creates the
|
||||
"my-new-feature" branch. This is important as you'll be basing your patches
|
||||
against that. Hence:
|
||||
|
||||
$ git checkout master
|
||||
$ git pull
|
||||
$ git checkout my-new-feature
|
||||
|
||||
(Note: It's conceivable here that the "my-new-feature" branch might undergo
|
||||
rebasing against origin/master -- although that's not being mentioned
|
||||
here in the general case, but would equally be acceptable.)
|
||||
|
||||
Compiling/Testing patches
|
||||
=========================
|
||||
|
||||
Before you send patches to the mailing list, please ensure that you compile
|
||||
tmux, as in the following:
|
||||
|
||||
$ make clean && ./autogen.sh && ./configure && make
|
||||
|
||||
This not only compiles with "-g" (for debug symbols), but also runs
|
||||
some sanity check to ensure you've not missed anything. If you have, fix up
|
||||
any warnings or errors, and repeat the above command until it's clean.
|
||||
|
||||
Generating patches to send to the mailing list
|
||||
==============================================
|
||||
|
||||
So, you've been working hard on your new feature, all your changes are sat
|
||||
in a local topic branch; "my-new-feature", and you want to submit them to
|
||||
the list. You've already updated your copy of the master branch, and
|
||||
your "my-new-feature" branch is checked-out, hence:
|
||||
|
||||
$ git format-patch -M -n --cover-letter -o patch_store master
|
||||
|
||||
Which will place a series of numbered commits in a directory called
|
||||
"patch_store". These can then be sent to the list [3] using the
|
||||
"git send-email" command.
|
||||
|
||||
Note that if this is more a bug-fix, or a single patch, it's not always
|
||||
necessary to generate a cover-letter -- so that option to "git format-patch"
|
||||
can be elided if necessary, but it doesn't really matter.
|
||||
|
||||
External hosting and pull-requests
|
||||
==================================
|
||||
|
||||
Alternatively, if using a hosted Git service [4], then it's acceptable
|
||||
that a pull-request can be issued on a branch against a repository.
|
||||
|
||||
Note that Thomas Adam has a Github repository [5] for tmux which is kept in
|
||||
sync with the tmux repo on sourceforge.
|
||||
|
||||
References
|
||||
==========
|
||||
|
||||
[1] http://git-scm.com
|
||||
[2] https://sourceforge.net/scm/?type=git&group_id=200378
|
||||
[3] tmux-users@lists.sourceforge.net
|
||||
[4] http://repo.or.cz -- or -- http://github.com
|
||||
[5] https://github.com/ThomasAdam/tmux
|
||||
Loading…
Reference in New Issue
Block a user